NonGNU-devel ELPA - pdf-tools

If you install pdf-tools via NonGNU ELPA or MELPA, you don't need to worry about this separate server installation at all.

Note: You'll need GNU Emacs ≥ 26.3 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.

The epdfinfo install script takes care of installing most of the necessary pre-requisites on supported operating systems (see list below). See the section on I want to add support for pdf-tools on My Fav OS. How do I do that? to learn how to add your favorite Operating System to this list.

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.

Pre-requisites:

• make: if this is not already installed, run ./server/autobuild instead of make -s
• cask: if this is not already installed, follow the install instructions from the cask github

Installation Instructions for epdfinfo:

$ git clone https://github.com/vedang/pdf-tools
$ cd pdf-tools
$ make -s

This should give you no error and should compile the epdfinfo server. If you face a problem, please report on the issue tracker!

The following Operating Systems / package managers are supported. Note: The package manager used to install pre-requisites should be installed on your OS for the script to work:

• Debian-based systems (debian, ubuntu): apt-get
• Fedora: dnf
• macOS: brew
• Windows (MSYS2/ MingW): pacman
• NixOS: nix-shell
• openSUSE (Tumbleweed and Leap): zypper
• Void Linux: xbps-install
• Apline Linux: apk
• FreeBSD: pkg
• OpenBSD: pkg_add
• NetBSD: pkgin
• Arch Linux: pacman
• Gentoo: emerge
• CentOS: yum

pdf-tools requires tablist package (>= version 0.70) to be installed, for it to work correctly. Please make sure that the latest version of tablist is installed.

We have already run the steps necessary to install pdf-tools as part of the server installation! These are:

$ git clone https://github.com/vedang/pdf-tools
$ cd /path/to/pdf-tools
$ make -s

If the make command 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-package

or executing the Emacs command

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

You can test if the package has been installed correctly, by running

M-x pdf-info-check-epdfinfo 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!

Some day you might want to update this package via git 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, run make distclean and then reinstall the package. Follow the steps described in Installing pdf-tools elisp code.

This also applies when updating via MELPA / NonGNU ELPA (except for running the make distclean step).

PDFView Mode is an Emacs PDF viewer. It displays PDF files as PNG images in Emacs buffers. PDFs are navigable using DocView-like bindings. Once you have installed pdf-tools, opening a PDF in Emacs will automatically trigger this mode.

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.

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.

Once you have read through the features provided by 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 RET

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

If you use display-line-numbers-mode globally, you should disable it for pdf-view-mode:

(add-hook 'pdf-view-mode-hook (lambda () (display-line-numbers-mode -1)))

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)

L/R scrolling breaks while zoomed into a pdf, with usage of sublimity smooth scrolling features

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: "))).

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

You can go to the pdf-tools folder and run make test to run the ERT tests and check if the changes you have made to the code break any of the tests.

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

You can go to the pdf-tools folder and run make server-test to check if the changes you have made to the server code break compilation on any of the supported operating systems.

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)

The server/test/docker folder contains Dockerfile templates used for testing that the epdfinfo server compiles correctly on various operating systems (more details here).

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)

Please use the 'Bug Report' issue template when reporting bugs. The template is as follows:

Have you upgraded poppler recently? This can cause epdfinfo to stop working, since it was compiled with the previous version of poppler. Just run M-x pdf-tools-install and this should be fixed.

pdf-tools version 1.1.0 release changed the default value of pdf-view-use-scaling to t (previously, it was nil). This has been done keeping in mind that most modern monitors are HiDPI screens, so the default configuration should cater to this user. If you are not using a HiDPI screen, you might have to change this value to nil in your configuration

(setq pdf-view-use-scaling nil)

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

I'm working on automating pdf-tools installation as much as possible, in order to improve the installation experience. If you want to add support for a new / currently unsupported Operating System, please modify the server/autobuild script. Say you want to support a new Operating System called MyFavOS. You need to do the following work:

1. Search for the Figure out where we are section. Here, add a call to os_myfavos right below 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.

If make -s or M-x pdf-tools-install fails with errors like Package 'poppler' not found or Package 'gpgmepp', required by 'poppler', not found, the most common cause is that a non-Homebrew pkg-config is being used (e.g., from Anaconda/Miniconda).

Step 1: Check which pkg-config is being used

which pkg-config

If this shows something other than /opt/homebrew/bin/pkg-config (Intel Macs: /usr/local/bin/pkg-config), that's likely the problem.

Step 2a: Fix for command-line builds

Force Homebrew's pkg-config before running the build:

export PKG_CONFIG=/opt/homebrew/bin/pkg-config
./server/autobuild

Step 2b: Fix for M-x pdf-tools-install within Emacs

If Emacs is picking up the wrong pkg-config, add this to your init file (thanks to @eli-tziperman):

;; Fix pdf-tools build on macOS when another pkg-config shadows Homebrew's
(when (eq system-type 'darwin)
  (let* ((brew-prefix (string-trim (shell-command-to-string "brew --prefix")))
         (brew-bin (concat brew-prefix "/bin"))
         (brew-sbin (concat brew-prefix "/sbin"))
         (pc-path (concat brew-prefix "/lib/pkgconfig:"
                          brew-prefix "/share/pkgconfig")))
    (setenv "PATH" (concat brew-bin ":" brew-sbin ":" (getenv "PATH")))
    (setq exec-path (append (list brew-bin brew-sbin) exec-path))
    (setenv "PKG_CONFIG" (concat brew-bin "/pkg-config"))
    (setenv "PKG_CONFIG_PATH" pc-path)))

Then restart Emacs and run M-x pdf-tools-install again.

Note: The ./server/autobuild script already adjusts PKG_CONFIG_PATH on macOS for keg-only packages, so prefer running it directly if you encounter path-related issues.

There have been a number of issues around pdf-tools installation problems on M1. M-x pdf-tools-install throws the following 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.

Thank you for taking the time to contribute back to the code. You may find some useful notes in the Tips and Tricks for Developers section. Please be sure to check it out!

Use C-c C-p (pdf-misc-print-document) to print the current PDF. By default, this command prompts for a print program. To avoid the prompt, configure the print program:

(setq pdf-misc-print-program-executable "lpr")

Note: print-buffer does not work with pdf-tools because it prints buffer text, which pdf-tools hides using overlays while displaying rendered page images.

Use M-x browse-url-of-file to open the current PDF in your system's default external PDF viewer.