To install this package, run in Emacs:
M-x package-install RET pdf-tools RET
https://circleci.com/gh/vedang/pdf-tools.svg?style=svg 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.
PDF Tools is, among other things, a replacement of DocView for PDF files. The key difference is that pages are not pre-rendered by, say, ghostscript
and stored in the file-system, but rather created on-demand and stored in memory.
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 this package via NonGNU ELPA or MELPA or any of the other package managers is straightforward and should just work! You should not require any manual changes. The documentation below is only if you are installing from source, or for troubleshooting / debugging purposes.
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. The following steps need to be followed in this order, to install pdf-tools
and epdfinfo
correctly:
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 all the necessary pre-requisites on supported operating systems (see list below). See the section on 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 to avoid manual installation of server / server prerequisites.
Installation Instructions for epdfinfo
:
$ git clone https://github.com/vedang/pdf-tools $ cd /path/to/pdf-tools $ make -s # If you don't have make installed, run ./server/autobuild and it will install make
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
, ubuntu
): apt-get
dnf
brew
pacman
nix-shell
zypper
xbps-install
apk
pkg
pkg_add
pacman
emerge
yum
pdf-tools
can be directly installed from the package manager on some operating systems. Note that the packages available on these package managers are not maintained by the author and might be outdated.
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.
mingw64
shell (Note: You must use mingw64.exe
and not msys2.exe
)epdfinfo
server using Installation steps described inserver/epdfinfo.exe
. Copy this file into the pdf-tools/
installation directory in your Emacs.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.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. Please use MSYS2.
On macOS, autobuild
adjusts PKG_CONFIG_PATH
so that pdf-tools
can find some of the keg-only packages installed by brew
. It is recommended that you review the output logs printed by brew
during the installation process to also export the relevant paths to the appropriate ENV variables.
In case you decide to install libpoppler
from source, make sure to run its configure script with the --enable-xpdf-headers
option.
One feature – following links of a PDF document by plain keystrokes – requires imagemagick
's convert utility. This requirement is optional, the installation process will detect if you have imagemagick
installed or not.
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 ! 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 and 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 .
This also applies when updating via MELPA / NonGNU ELPA (except for running the make distclean
step).
imenu
or a special buffer (M-x pdf-outline
) to examine and navigate the PDF's outline.
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.
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 | < , M-< / > , M-> |
Next Page / Previous Page | n / p |
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 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.
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 ().
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)
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:
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.--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.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.epdfinfo
continues to compile correctly. See 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 as well as as described in the linked articles.
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, , 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 section. Please be sure to check it out!
pdf-tools-1.0.tar.lz | 2021-Dec-03 | 370 KiB |
-*- org -*- * Version 1.0.0 (Under Development) From this version onward, we will follow Semantic Versioning for new ~pdf-tools~ releases. ** Breaking changes: *** Raise the minimum supported version of Emacs to 26.3 #26 Drop support for Emacs 24 and 25. This allows for some code cleanup. *This is a major breaking change*. *** Change the default value of pdf-view-use-scaling #133 ~pdf-view-use-scaling~ is now true by default, leading to rendering of crisp images on high-resolution screens. This should not cause problems on low-resolution screen (other than taking up more cache space / increasing rendering time), but if it does, please ~(setq pdf-view-use-scaling nil)~ in your configuration. ** Improve overall user experience - Set ~pdf-annot-list-highlight-type~ to true by default. + Show annotation color when listing them by default, allow the user to turn them off if need be. ** Make changes required by newer versions of Emacs - Emacs 29 introduces ~pixel-scroll-precision-mode~, which interferes with ~pdf-view~ scrolling. This is fixed in #124 ** Functionality fixes and improvements - Fix ~revert-buffer~ to correctly work over Tramp #128 - Fix sorting by date in ~pdf-annot-list-mode~ #75 * Version 0.91 ** Change the keybindings for traversing history This is a minor but *breaking change*. ~l~ (backward) and ~r~ (forward) are the conventional bindings for history navigation in Emacs, but ~pdf-tools~ uses ~B~ and ~N~. The previous keybindings are kept as-is for people who were used to it, while introducing ~l~ and ~r~ keybindings as well. This is a breaking change because ~r~ was previously bound to ~revert-buffer~. However, ~g~ is also bound to ~revert-buffer~ and is the conventional binding for ~revert~ so this should be okay. ** Make changes required by newer versions of Emacs A number of changes are made to support new elisp / package changes. There is no impact of this on existing users. - Emacs 27, Emacs 28 and Emacs 29 are supported now. - Synctex 1.21 is supported now. ** Improve overall install experience Running ~M-x pdf-tools-install~ should _just work_ now. ** Add support for high-resolution displays (Retina display on Mac) Setting ~pdf-view-use-scaling~ to a non-nil value now renders crisp images on high-resolution displays. * Version 0.90 ** The displayed columns when listing annotations is now customizable See variable ~pdf-annot-list-format~ and ~pdf-annot-list-highlight-type~. ** Improved handling of default annotation properties A new variable ~pdf-annot-default-annotation-properties~ was introduced, subsuming and obsoleting ~pdf-annot-default-text-annotation-properties~ and ~pdf-annot-default-markup-annotation-properties~. The new variable lets the user choose default properties, e.g. a color, for all supported annotations separately. ** Provide a faster "boot-loader" The autoloaded function ~pdf-loader-install~ acts as a replacement for ~pdf-tools-install~ and makes Emacs load and use PDF Tools as soon as a PDF file is opened, but not sooner. ** Improved the process of (re)compiling the server This obsoletes the variable ~pdf-tools-handle-upgrades~, which does nothing anymore. * Version 0.80 ** Tablist package The files ~tablist.el~ and ~tablist-filter.el~ are no longer part of ~pdf-tools~, but continue to live on in the ~tablist~ package, on which ~pdf-tools~ now depends on. ** View *** Encrypted files When encountering an encrypted file, query for a password and attempt to decrypt it. *** Backward sync from isearch In ~isearch~, press ~M-s s~ to visit the source of the current match. *** Disable unicode in mode-line New variable ~pdf-view-use-unicode-lighter~ which allows for disabling the use of unicode in the mode-line. * Version 0.70 ** View *** Register integration The keys ~m~ and ~'~ now set respectively to jump to a register corresponding to a position in the PDF. Also ~''~ is handled special: It jumps to the position before the last register-jump. *** Export parts of a page as an image See ~pdf-view-extract-region-image~. ... ...