The pdf-tools Wiki is maintained at https://pdftools.wiki. Head to the site if you find it easier to navigate a website for reading a manual. All the topics on the site are listed at https://pdftools.wiki/impulse.
This rendering is performed by a special library named, for whatever reason, poppler, running inside a server program. This program is called epdfinfo and its job is to successively read requests from Emacs and produce the proper results, i.e. the PNG image of a PDF page.
Actually, displaying PDF files is just one part of pdf-tools. Since poppler can provide us with all kinds of information about a document and is also able to modify it, there is a lot more we can do with it. Watch this video for a detailed demo!
pdf-tools requires a server epdfinfo to run against, which it will try to compile and build when it is activated for the first time.
You should not require any manual changes. The documentation below is if you are installing from source, or for troubleshooting / debugging purposes.
- Installing
epdfinfoserver prerequisites - Compiling and Installing the
epdfinfoserver - Installing
pdf-toolselisp prerequisites - Installing
pdf-toolselisp code
pdf-tools is known to work on many of them. See links below for more details. The following instructions assume a Debian-based system.
First make sure a suitable build-system is installed. We need at least a C/C++ compiler (both gcc and g++), make, automake and autoconf.
Next we need to install a few libraries pdf-tools depends on, some of which are probably already on your system.
$ sudo apt install libpng-dev zlib1g-dev libpoppler-glib-dev libpoppler-private-devOn some older Ubuntu systems, the final command will possibly give an error. This should be no problem, since in some versions this package was contained in the main package libpoppler-dev. Also note, that zlib1g-dev was for a long time called libz-dev, which it still may be on your system.
Debian wheezy comes with libpoppler version 0.18, which is pretty old. The minimally required version is 0.16, but some features of pdf-tools depend on a more recent version of this library. See the following table for what they are and what version they require.
| You want to … | Required version |
|---|---|
| … create and modify text annotations. | ≥ 0.19.4 |
| … search case-sensitive. | ≥ 0.22 |
| … create and modify markup annotations. | ≥ 0.26 |
In case you decide to install libpoppler from source, make sure to run its configure script with the --enable-xpdf-headers option.
Finally there is one feature (following links of a PDF document by plain keystrokes) which requires imagemagick’s convert utility. This requirement is optional and you may install it like so:
$ sudo apt install imagemagickpdf-tools works well on macOS. You will need to install poppler which you can get with Homebrew via
$ brew install poppler automakeYou will also have to help pkg-config find some libraries by setting PKG_CONFIG_PATH, e.g.
$ export PKG_CONFIG_PATH=/usr/local/Cellar/zlib/1.2.8/lib/pkgconfig:/usr/local/lib/pkgconfig:/opt/X11/lib/pkgconfigor likewise within Emacs using setenv.
After that, compilation should proceed as normal.
Although not officially supported, it has been reported thatpdf-tools work well on FreeBSD. Instead of building pdf-tools, you can install one of the OS packages with e.g.
$ pkg install pdf-tools-emacs26To see the current list of pdf-tools packages for FreeBSD visit the Repology list.
To build pdf-tools from either MELPA or directly from the source repository, install the dependencies with
$ pkg install autotools gmake poppler-glibIf you choose not to install from MELPA, you must substitute gmake for make in the instructions below.
$ yum install poppler-devel poppler-glib-devel$ sudo dnf install make automake autoconf gcc gcc-c++ ImageMagick libpng-devel zlib-devel poppler-glib-devel$ apk add build-base g++ gcc automake autoconf libpng-dev glib-dev poppler-devpdf-tools can be built and used on Windows using the MSYS2 compiler. This will work with native (not cygwin) Windows builds of Emacs. This includes the standard binaries provided by the GNU project, those available as MSYS2 packages and numerous third-party binaries. It has been tested with Emacs 25.1. Instructions are provided under Compilation and installation on Window below. pdf-tools will successfully compile using Cygwin, but it will not be able to open PDFs properly due to the way binaries compiled with Cygwin handle file paths.
$ cd /path/to/pdf-tools
$ make -sThis should compile the source code and create a Emacs Lisp Package in the root directory of the project. The configure script also tells you at the very end, which features, depending on the libpoppler version, will be available. These commands should give no error, otherwise you are in trouble.
If using the GNU binaries for Windows, support for PNG andzlib must first be installed by copying the appropriate dlls into emacs’ bin/ directory. Most third-party binaries come with this already done.
First, install install MSYS2 and update the package database and core packages using the instructions provided. Then, to compile pdf-tools itself:
- Open msys2 shell
- Update and install dependencies, skipping any you already have
$ pacman -Syu
$ pacman -S base-devel
$ pacman -S mingw-w64-x86_64-toolchain
$ pacman -S mingw-w64-x86_64-zlib
$ pacman -S mingw-w64-x86_64-libpng
$ pacman -S mingw-w64-x86_64-poppler
$ pacman -S mingw-w64-x86_64-imagemagick- Install
pdf-toolsin Emacs, but do not try to compile the server. Instead, get a separate copy of the source somewhere else.
$ git clone https://github.com/vedang/pdf-tools- Open
mingw64shell (Note: You must usemingw64.exeand notmsys2.exe) - Compile pdf-tools
$ cd /path/to/pdf-tools
$ make -s- This should produce a file
server/epdfinfo.exe. Copy this file into thepdf-tools/installation directory in your Emacs. - Start Emacs and activate the package.
M-x pdf-tools-install RET
- Test.
M-x pdf-info-check-epdfinfo RET
If this is successful, (pdf-tools-install) can be added to Emacs’ config. Note that libraries from other GNU utilities, such as Git for Windows, may interfere with those needed by pdf-tools. pdf-info-check-epdinfo will succeed, but errors occur when trying to view a PDF file. This can be fixed by ensuring that the MSYS libraries are always preferred in Emacs:
(setenv "PATH" (concat "C:\\msys64\\mingw64\\bin;" (getenv "PATH")))pdf-tools package.
| Package | Required version |
|---|---|
| let-alist | >= 1.0.4 (comes with Emacs 25.2) |
| tablist | >= 0.70 |
make produced the ELP file pdf-tools-${VERSION}.tar you are fine. This package contains all the necessary files for Emacs and may be installed by either using
$ make install-packageor executing the Emacs command
M-x package-install-file RET pdf-tools-${VERSION}.tar RETTo complete the installation process, you need to activate the package by putting the code below somewhere in your .emacs. Alternatively, and if you care about startup time, you may want to use the loader version instead.
(pdf-tools-install) ; Standard activation command
(pdf-loader-install) ; On demand loading, leads to faster startup timeOnce the Installation process is complete, check out Easy Help for PDF Tools features and Configuring PDF Tools features to get started!
Some day you might want to update this package viagit pull and then reinstall it. Sometimes this may fail, especially if Lisp-Macros are involved and the version hasn’t changed. To avoid this kind of problems, you should delete the old package via list-packages, restart Emacs and then reinstall the package.
This also applies when updating via package and MELPA.
- View
- View PDF documents in a buffer with DocView-like bindings. More information here.
- Isearch
- Interactively search PDF documents like any other buffer, either for a string or a PCRE.
- Occur
- List lines matching a string or regexp in one or more PDF documents.
- Follow
- Click on highlighted links, moving to some part of a different page, some external file, a website or any other URI. Links may also be followed by keyboard commands.
- Annotations
- Display and list text and markup annotations (like underline), edit their contents and attributes (e.g. color), move them around, delete them or create new ones and then save the modifications back to the PDF file. More information here.
- Attachments
- Save files attached to the PDF-file or list them in a dired buffer.
- Outline
- Use
imenuor a special buffer (M-x pdf-outline) to examine and navigate the PDF’s outline. - SyncTeX
- Jump from a position on a page directly to the TeX source and vice versa.
- Virtual
- Use a collection of documents as if it were one, big single PDF.
- Misc
-
- Display PDF’s metadata.
- Mark a region and kill the text from the PDF.
- Keep track of visited pages via a history.
- Apply a color filter for reading in low light conditions.
pdf-tools, opening a PDF in Emacs will automatically trigger this mode.
| Navigation | |
|---|---|
| Scroll Up / Down by Page-full | space / backspace |
| Scroll Up / Down by Line | C-n / C-p |
| Scroll Right / Left | C-f / C-b |
| First Page / Last Page | < / > |
| Next Page / Previous Page | n / p |
| First Page / Last Page | M-< / M-> |
| Incremental Search Forward / Backward | C-s / C-r |
| Occur (list all lines containing a phrase) | M-s o |
| Jump to Occur Line | RETURN |
| Pick a Link and Jump | F |
| Incremental Search in Links | f |
| History Back / Forwards | l / r |
| Display Outline | o |
| Jump to Section from Outline | RETURN |
| Jump to Page | M-g g |
| Store position / Jump to position in register | m / ~’~ |
Note that pdf-tools renders the PDF as images inside Emacs. This means that all the keybindings of image-mode work on individual PDF pages as well.
| Image Mode | |
|---|---|
| image-scroll-right | C-x > / <remap> <scroll-right> |
| image-scroll-left | C-x < / <remap> <scroll-left> |
| image-scroll-up | C-v / <remap> <scroll-up> |
| image-scroll-down | M-v / <remap> <scroll-down> |
| image-forward-hscroll | C-f / right / <remap> <forward-char> |
| image-backward-hscroll | C-b / left / <remap> <backward-char> |
| image-bob | <remap> <beginning-of-buffer> |
| image-eob | <remap> <end-of-buffer> |
| image-bol | <remap> <move-beginning-of-line> |
| image-eol | <remap> <move-end-of-line> |
| image-scroll-down | <remap> <scroll-down> |
| image-scroll-up | <remap> <scroll-up> |
| image-scroll-left | <remap> <scroll-left> |
| image-scroll-right | <remap> <scroll-right> |
| Display | |
|---|---|
| Zoom in / Zoom out | + / - |
| Fit Height / Fit Width / Fit Page | H / W / P |
| Trim Margins (set slice to bounding box) | s b |
| Reset Margins | s r |
| Reset Zoom | 0 |
pdf-tools supports working with PDF Annotations. You can display and list text and markup annotations (like squiggly, highlight), edit their contents and attributes (e.g. color), move them around, delete them or create new ones and then save the modifications back to the PDF file.
| Annotations | |
|---|---|
| List Annotations | C-c C-a l |
| Jump to Annotations from List | SPACE |
| Mark Annotation for Deletion | d |
| Delete Marked Annotations | x |
| Unmark Annotations | u |
| Close Annotation List | q |
| Enable/Disable Following Annotations | C-c C-f |
| Add and Edit Annotations | Select region via Mouse selection. |
| Then left-click context menu OR keybindings below | |
| Add a Markup Annotation | C-c C-a m |
| Add a Highlight Markup Annotation | C-c C-a h |
| Add a Strikeout Markup Annotation | C-c C-a o |
| Add a Squiggly Markup Annotation | C-c C-a s |
| Add an Underline Markup Annotation | C-c C-a u |
| Add a Text Annotation | C-c C-a t |
| Syncing with AUCTeX | |
|---|---|
| Refresh File (e.g., after recompiling source) | g |
| Jump to PDF Location from Source | C-c C-g |
| Jump Source Location from PDF | C-mouse-1 |
| Miscellaneous | |
|---|---|
| Print File | C-c C-p |
M-x pdf-tools-help RETRun M-x pdf-tools-help inside Emacs, as shown above. It will list all the features provided by pdf-tools as well as the key-bindings for these features.
pdf-tools, you probably want to customize the behavior of the features as per your requirements. Full customization of features is available by running the following:
M-x pdf-tools-customize RETpdf-tools does not work well together with linum-mode and activating it in a pdf-view-mode, e.g. via global-linum-mode, might make Emacs choke.
This mode is an alternative to linum-mode and is available since Emacs 26. pdf-tools does not work well with it. For example, it makes horizontal navigation (such as C-f, C-b, C-x < or C-x > ) in a document impossible.
Autorevert works by polling the file-system every auto-revert-interval seconds, optionally combined with some event-based reverting via file notification. But this currently does not work reliably, such that Emacs may revert the PDF-buffer while the corresponding file is still being written to (e.g. by LaTeX), leading to a potential error.
With a recent AUCTeX installation, you might want to put the following somewhere in your dotemacs, which will revert the PDF-buffer after the TeX compilation has finished.
(add-hook 'TeX-after-compilation-finished-functions #'TeX-revert-document-buffer)- Keybindings for navigating PDF documents
- Keybindings for working with Annotations
- Keybindings for manipulating display of PDF
- Keybindings for working with AUCTeX
- Keybindings for miscellaneous features in PDF tools
M-x pdf-tools-toggle-debug RETToggling debug mode prints information about various operations in the *Messages* buffer, and this is useful to see what is happening behind the scenes
(setq pdf-view-use-scaling t)to scale the images correctly when rendering them.
pdf-tools supports the 3 latest versions of Emacs major releases. At the moment of this writing, this means that the minimum supported Emacs version is 25.1.