PDF Tools README

https://ci.appveyor.com/api/projects/status/yqic2san0wi7o5v8/branch/master?svg=true

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.

About PDF Tools

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!

Installing pdf-tools

You should not require any manual changes. The documentation below is only if you are installing from source, or for troubleshooting / debugging purposes. The following steps need to be followed in this order, to install pdf-tools and epdfinfo correctly:

• Installing epdfinfo server prerequisites
• Installing the epdfinfo server
• Installing pdf-tools elisp prerequisites
• Installing pdf-tools elisp code

Installing epdfinfo server prerequisites

Note: You’ll need GNU Emacs ≥ 26.1 and some form of a GNU/Linux OS. Other operating systems are not officially supported, but pdf-tools is known to work on many of them.

Similarly, package-managers are not officially supported, but pdf-tools is known to be available on some of them. See the section on Installing the epdfinfo server from package managers to avoid manual installation of server / server prerequisites.

See the section on I want to add support for pdf-tools on My Fav OS. How do I do that? to add your favorite Operating System to this list.

Installing epdfinfo Server Prerequisites on a Debian-based system

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

On 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.

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 imagemagick

Installing epdfinfo Server Prerequisites On macOS

$ brew install poppler automake

You will also have to help pkg-config find some libraries by setting PKG_CONFIG_PATH. brew will show you which paths need to be added to PKG_CONFIG_PATH during the installation process. Make sure you export the paths to the env variable, eg:

$ export PKG_CONFIG_PATH="${PKG_CONFIG_PATH}:$(brew --prefix libffi)/lib/pkgconfig/:/usr/local/Cellar/zlib/1.2.8/lib/pkgconfig:/usr/local/lib/pkgconfig:/opt/X11/lib/pkgconfig"

or likewise within Emacs using setenv.

After that, compilation should proceed as normal.

Installing epdfinfo Server Prerequisites On FreeBSD

$ pkg install pdf-tools-emacs26

To 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-glib

If you choose not to install from MELPA, you must substitute gmake for make in the instructions below.

Installing epdfinfo Server Prerequisites On CentOS

$ yum install poppler-devel poppler-glib-devel

Installing epdfinfo Server Prerequisites On Fedora

$ sudo dnf install make automake autoconf gcc libpng-devel zlib-devel poppler-glib-devel

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 dnf install imagemagick

Installing epdfinfo Server Prerequisites On openSUSE

$ sudo zypper install make automake autoconf gcc libpng16-devel libpng16-compat-devel zlib-devel libpoppler-devel libpoppler-glib-devel glib2-devel

For openSUSE MicroOS Desktop:

$ pkcon install make automake autoconf gcc libpng16-devel libpng16-compat-devel zlib-devel libpoppler-devel libpoppler-glib-devel glib2-devel

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 the imagemagick package via the package manager of your choice.

Installing epdfinfo Server Prerequisites On Alpine Linux

$ apk add build-base gcc automake autoconf libpng-dev glib-dev poppler-dev

Installing epdfinfo Server Prerequisites On Windows

The pre-built binaries will work with native (not Cygwin) Windows builds of Emacs. They include the standard binaries provided by the GNU project, those available as MSYS2 packages and numerous third-party binaries. Refer to the appropriate section under Installing the epdfinfo server for more details.

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.

Installing the epdfinfo server

Compiling and Installing the epdfinfo server from source on Linux

$ cd /path/to/pdf-tools
$ make -s

This 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.

Compiling and Installing the epdfinfo server from source on Windows

If using the GNU binaries for Windows, support for PNG and zlib must first be installed by copying the appropriate dlls into emacs’ bin/ directory. Most third-party binaries come with this already done.

First, install MSYS2 and update the package database and core packages using the instructions provided. Then, to compile pdf-tools itself:

1. Open msys2 shell
2. 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
       

3. Install pdf-tools in 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
       

4. Open mingw64 shell (Note: You must use mingw64.exe and not msys2.exe)
5. Compile pdf-tools

   $ cd /path/to/pdf-tools
   $ make -s
       

6. This should produce a file server/epdfinfo.exe. Copy this file into the pdf-tools/ installation directory in your Emacs.
7. Start Emacs and activate the package.

   M-x pdf-tools-install RET
       

8. Test.

   M-x pdf-info-check-epdfinfo RET
       

If this is successful, (pdf-tools-install) can be added to Emacs’ config. See the note on how to set up PATH in the previous section.

Installing the epdfinfo server from package managers

Using the pre-built MINGW packages from MSYS2 on Windows

Users installing Emacs from the MSYS2 distribution can install pre-built binaries of the epdfinfo server.

1. Install MSYS2 and update the package database and core packages using the instructions provided.
2. Install packages: pacman -Ss mingw-w64-x86_64-{emacs,emacs-pdf-tools-server,imagemagick} (ImageMagick is optional, see above.)
3. Make sure Emacs can find epdfinfo.exe. Either add the MINGW install location (e.g. C:/msys2/mingw64/bin) to the system path with setx PATH "C:\msys2\mingw64\bin;%PATH%"~ or set Emacs's path with ~(setenv "PATH" (concat "C:\\msys64\\mingw64\\bin;" (getenv "PATH"))). 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.
4. Add (pdf-tools-install) to your Emacs config.

Using the pre-built packages from Debian

Using the pre-built packages from Ubuntu

Installing pdf-tools elisp prerequisites

Installing pdf-tools elisp code

$ make install-package

or executing the Emacs command

M-x package-install-file RET pdf-tools-${VERSION}.tar RET

To 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 time

Once the Installation process is complete, check out Easy Help for PDF Tools features and Configuring PDF Tools features to get started!

Updating pdf-tools

This also applies when updating via package and MELPA.

Features

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 imenu or 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.

View and Navigate PDFs

Keybindings for navigating PDF documents

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.

Keybindings for manipulating display of PDF

Annotations

Keybindings for working with Annotations

Working with AUCTeX

Keybindings for working with AUCTeX

Miscellaneous features

Keybindings for miscellaneous features in PDF tools

Easy Help for PDF Tools features

M-x pdf-tools-help RET

Run 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.

Configuring PDF Tools features

M-x pdf-tools-customize RET

Known problems

linum-mode

display-line-numbers-mode

auto-revert

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)

sublimity

Text selection is not transparent in PDFs OCRed with Tesseract

In such PDFs the selected text becomes hidden behind the selection; see this issue, which also describes the workaround in detail. The following function, which depends on the qpdf.el package, can be used to convert such a PDF file into one where text selection is transparent:

(defun my-fix-pdf-selection ()
  "Replace pdf with one where selection shows transparently."
  (interactive)
  (unless (equal (file-name-extension (buffer-file-name)) "pdf")
    (error "Buffer should visit a pdf file."))
  (unless (equal major-mode 'pdf-view-mode)
    (pdf-view-mode))
  ;; save file in QDF-mode
  (qpdf-run (list
             (concat "--infile="
                     (buffer-file-name))
             "--qdf --object-streams=disable"
             "--replace-input"))
  ;; do replacements
  (text-mode)
  (read-only-mode -1)
  (while (re-search-forward "3 Tr" nil t)
    (replace-match "7 Tr" nil nil))
  (save-buffer)
  (pdf-view-mode))

Note that this overwrites the PDF file visited in the buffer from which it is run! To avoid this replace the --replace-input with (concat "--outfile=" (file-truename (read-file-name "Outfile: "))).

Key-bindings in PDF Tools

• 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

Tips and Tricks for Developers

Turn on debug mode

M-x pdf-tools-toggle-debug RET

Toggling debug mode prints information about various operations in the *Messages* buffer, and this is useful to see what is happening behind the scenes

Run Emacs lisp tests locally

The tests are written in ERT, which is the built-in testing system in Emacs. However, they are run using Cask which you will have to install first, if you don’t have it already. You can install Cask by following the instructions on their site at https://github.com/cask/cask

Run server compilation tests locally

The tests build Podman images for all supported operating systems, so you will have to install Podman first, if you don’t have already. You can install Podman by following the instructions on their site at https://podman.io/getting-started/installation

Podman is compatible with Docker, so if you already have docker installed, you should be able to alias podman=docker on your shell and run the tests, without having to install Docker. (Note: I have not tested this)

Add a Dockerfile to automate server compilation testing

To see the list of operating systems where compilation testing is supported, run make server-test-supported. To see the list of operating systems where testing is unsupported, run make server-test-unsupported. To add support, look into the server/test/docker/templates folder (ubuntu files are a good example to refer to)

FAQs

I’m on a Macbook and PDFs are rendering blurry

(setq pdf-view-use-scaling t)

to scale the images correctly when rendering them.

What Emacs versions does pdf-tools support?

I want to add support for pdf-tools on My Fav OS. How do I do that?

1. Add a call to os_myfavos under handle-options at the end of the existing call chain. Here we try and pick up the correct Operating System and install the relevant dependencies.
2. Add handling for the --os argument in os_argument for myfavos, so that the appropriate function can be called to install pre-requisites. --os is the argument that we pass to the script from the command-line to indicate which OS we are on.
3. Create a os_myfavos function. This function checks if we are running on MyFavOS. If we are running on MyFavOS, it sets up PKGCMD, PKGARGS and PACKAGES variables so that the appropriate package manager can install the dependencies as part of the rest of the autobuild script.
4. If you are adding support for your favorite operating system, consider adding automated testing support as well, to help me ensure that epdfinfo continues to compile correctly. See Add a Dockerfile to automate server compilation testing for more details.

The idea here is to make the server/autobuild file the single place from which installation can happen on any Operating System. This makes building pdf-tools dead simple via the Makefile.

This seems like a lot of work, but it is not. If you need a reference, search for os_gentoo or os_debian in the server/autobuild file and see how these are setup and used. The functions are used to install dependencies on Gentoo and Debian respectively, and are simple to copy / change.

When you make your changes, please be sure to test the elisp changes as well as the server code changes as described in the linked articles.

I am on a Macbook M1 and pdf-tools installation fails with a stack-trace

1 warning generated.
ld: warning: ignoring file /opt/homebrew/opt/gettext/lib/libintl.dylib, building for macOS-x86_64 but attempting to link with file built for macOS-arm64
ld: warning: ignoring file /opt/homebrew/Cellar/glib/2.72.1/lib/libglib-2.0.dylib, building for macOS-x86_64 but attempting to link with file built for macOS-arm64
ld: warning: ignoring file /opt/homebrew/Cellar/poppler/22.02.0/lib/libpoppler-glib.dylib, building for macOS-x86_64 but attempting to link with file built for macOS-arm64
ld: warning: ignoring file /opt/homebrew/Cellar/glib/2.72.1/lib/libgobject-2.0.dylib, building for macOS-x86_64 but attempting to link with file built for macOS-arm64
ld: warning: ignoring file /opt/homebrew/Cellar/poppler/22.02.0/lib/libpoppler.dylib, building for macOS-x86_64 but attempting to link with file built for macOS-arm64
ld: warning: ignoring file /opt/homebrew/Cellar/cairo/1.16.0_5/lib/libcairo.dylib, building for macOS-x86_64 but attempting to link with file built for macOS-arm64
ld: warning: ignoring file /opt/homebrew/Cellar/libpng/1.6.37/lib/libpng16.dylib, building for macOS-x86_64 but attempting to link with file built for macOS-arm64
ld: warning: ignoring file /opt/homebrew/Cellar/zlib/1.2.11/lib/libz.dylib, building for macOS-x86_64 but attempting to link with file built for macOS-arm64
Undefined symbols for architecture x86_64:

This happens because M1 architecture is ARM64, whereas the Emacs App you are using has been compiled for the x86_64 architecture. The way to solve this problem is to install a version of Emacs which has been compiled for the M1. As of today, [2022-05-09 Mon], the latest version of Emacs available on https://emacsformacosx.com/ is natively compiled and you will not face these issues on it. Please remove your current Emacs App and install it from https://emacsformacosx.com/.

Thank you.

PS: How do I know if the Emacs I’m running has been compiled correctly?

You can see this by opening the Activity Monitor, selecting Emacs, clicking on the Info key, and then clicking on Sample. The Code Type field in the Sample output will show you how your Application has been compiled. Here is the output for EmacsForMacOSX (you can see that it’s ARM64):

Sampling process 61824 for 3 seconds with 1 millisecond of run time between samples
Sampling completed, processing symbols...
Analysis of sampling Emacs-arm64-11 (pid 61824) every 1 millisecond
Process:         Emacs-arm64-11 [61824]
Path:            /Applications/Emacs.app/Contents/MacOS/Emacs-arm64-11
Load Address:    0x1007f0000
Identifier:      org.gnu.Emacs
Version:         Version 28.1 (9.0)
Code Type:       ARM64
Platform:        macOS

If your Emacs is compiled for x86, the Code Type will be x86_64.

I am a developer, making changes to the pdf-tools source code