Are you happy with your logging solution? Would you help us out by taking a 30-second survey? Click here

pdf-tools

Emacs support library for PDF files.

Subscribe to updates I use pdf-tools


Statistics on pdf-tools

Number of watchers on Github 747
Number of open issues 73
Average time to close an issue 3 months
Main language Emacs Lisp
Average time to merge a PR 10 days
Open pull requests 25+
Closed pull requests 14+
Last commit almost 2 years ago
Repo Created over 6 years ago
Repo Last Updated over 1 year ago
Size 1.87 MB
Organization / Authorpolitza
Contributors7
Page Updated
Do you use pdf-tools? Leave a review!
View open issues (73)
View pdf-tools activity
View on github
Fresh, new opensource launches 🚀🚀🚀
Trendy new open source projects in your inbox! View examples

Subscribe to our mailing list

Evaluating pdf-tools for your project? Score Explanation
Commits Score (?)
Issues & PR Score (?)

+TITLE: PDF Tools README

+AUTHOR: Andreas Politz

+EMAIL: politza@fh-trier.de

[[https://travis-ci.org/politza/pdf-tools.svg?branch%3Dmaster][https://travis-ci.org/politza/pdf-tools.svg?branch=master]] [[https://coveralls.io/repos/politza/pdf-tools/badge.svg?branch=master&service=github][https://coveralls.io/github/politza/pdf-tools?branch=master]] [[http://stable.melpa.org/#/pdf-tools][http://stable.melpa.org/packages/pdf-tools-badge.svg]] [[http://melpa.org/#/pdf-tools][http://melpa.org/packages/pdf-tools-badge.svg]]

** About this package PDF Tools is, among other things, a replacement of DocView for PDF files. The key difference is that pages are not pre-rendered by e.g. 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. [[http://www.dailymotion.com/video/x2bc1is_pdf-tools-tourdeforce_tech?forcedQuality%3Dhd720][Watch]]

Please read also about [[#known-problems][known problems.]]

** Features

  • View :: View PDF documents in a buffer with DocView-like bindings.
  • 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.
  • Attachments :: Save files attached to the PDF-file or list them in a dired buffer.
  • Outline :: Use imenu or a special buffer 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.

** Installation The package may be installed via melpa and it will try to build the server part when it is activated the first time. Though the next section regarding build-prerequisites is still relevant, the rest of the installation instructions assume a build from within a git repository. (The melpa package has a different directory structure.)

*** Server Prerequisites You'll need GNU Emacs \ge 24.3 and some form of a GNU/Linux OS. Other operating systems are currently not supported (patches welcome). The following instructions assume a Debian-based system. (The prerequisites may be installed automatically on this kind of systems, see [[#compilation][Compilation]] .)

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.

+begin_src sh

$ sudo aptitude install libpng-dev zlib1g-dev $ sudo aptitude install libpoppler-glib-dev $ sudo aptitude install libpoppler-private-dev

+end_src

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.

| You want to ...                           | Required version |
|-------------------------------------------+------------------|
| ... create and modify text annotations.   | \ge 0.19.4       |
| ... search case-sensitive.                | \ge 0.22         |
| ... create and modify markup annotations. | \ge 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:

+begin_src sh

$ sudo aptitude install imagemagick

+end_src

**** Compiling on OS X Although OS X is not officially supported, it has been reported to have been successfully compiled. You will need to install poppler which you can get with homebrew via

+BEGIN_SRC sh

$ brew install poppler automake

+END_SRC

 You will also have to help ~pkg-config~ find some libraries by
 setting ~PKG_CONFIG_PATH~, e.g.

+BEGIN_SRC sh

$ export PKG_CONFIG_PATH=/usr/local/Cellar/zlib/1.2.8/lib/pkgconfig:/usr/local/lib/pkgconfig:/opt/X11/lib/pkgconfig

+END_SRC

 or likewise within Emacs using `setenv`.

 After that, compilation should proceed as normal.

**** Compiling on FreeBSD Although not officially supported, it has been reported that pdf-tools work well on FreeBSD. Install the dependencies with

+BEGIN_SRC sh

$ pkg install autotools gmake poppler-glib

+END_SRC

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

**** Compiling on Centos It is possible to compile pdf-tools on Centos. Install poppler the dependencies with:

+BEGIN_SRC sh

$ yum install poppler-devel poppler-glib-devel

+END_SRC

**** Compiling on Fedora

+BEGIN_SRC sh

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

+END_SRC

**** Compiling on Windows PDF 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 Windows]], below. **** Compiling on Cygwin On [[https://www.cygwin.com/][Cygwin]] the following dependencies are needed.

 - libpoppler-devel (*Lib* category)
 - libpoppler-glib-devel (*Lib* category)
 - libpng-devel (*Devel* category)
 - make (*Devel* category)
 - gcc-core (*Devel* category)
 - gcc-g++ (*Devel* category)
 - autoconf (*Devel* category)
 - automake (*Devel* category)
 - perl (*Perl* category)
 - emacs-w32 (*Editors* category)

*** Compilation :PROPERTIES: :CUSTOM_ID: compilation :END: Now it's time to compile the source.

+begin_src sh

$ cd /path/to/pdf-tools
$ make install-server-deps # optional
$ make -s

+end_src

The ~make install-server-deps~ command will try to install all
necessary programs and libraries to build the package, though
it'll only work, if ~sudo~ and ~apt-get~ are available.

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.

**** Compilation and installation 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 [[http://www.msys2.org/][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
     #+BEGIN_SRC sh
     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
     #+END_SRC

  3. Install PDF tools in Emacs, but do not try to compile the
     server. Instead, get a separate copy of the source somewhere
     else.
     #+BEGIN_SRC sh
     git clone https://github.com/politza/pdf-tools
     #+END_SRC

  4. Open mingw64 shell

  5. Compile pdf-tools
     #+BEGIN_SRC sh
     cd pdf-tools/build
     make -s
     #+END_SRC

  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.
     #+BEGIN_SRC
     M-x pdf-tools-install RET
     #+END_SRC

  8. Test.
     #+BEGIN_SRC
     M-x pdf-info-check-epdfinfo RET
     #+END_SRC

  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:

#+BEGIN_SRC emacs-lisp (setenv PATH (concat C:\\msys64\\mingw64\\bin; (getenv PATH))) #+END_SRC

*** ELisp Prerequisites This package depends on the following Elisp packages, which should be installed before installing the Pdf Tools package.

| Package   | Required version                 |
|-----------+----------------------------------|
| [[https://elpa.gnu.org/packages/let-alist.html][let-alist]] | >= 1.0.4 (comes with Emacs 25.2) |
| [[http://melpa.org/#/tablist][tablist]]   | >= 0.70                          |
|-----------+----------------------------------|

*** Installing If ~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

+begin_src sh

$ make install-package

+end_src

or executing the Emacs command

+begin_src elisp

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

+end_src

To complete the installation process, you need to activate the package by putting

+begin_src elisp

(pdf-tools-install)

+end_src

somewhere in your ~.emacs~. Next you probably want to take a look at the various features of what you've just installed. The following two commands might be of help for doing so.

+begin_src elisp

M-x pdf-tools-help RET M-x pdf-tools-customize RET

+end_src

*** Updating 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 and then reinstall the package.

This also applies when updating via package and melpa.

** Known problems :PROPERTIES: :CUSTOM_ID: known-problems :END:

*** linum-mode 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.

*** auto-revert Autorevert works by polling the file-system every ~auto-revert-interval~ seconds, optionally combined with some event-based reverting via [[https://www.gnu.org/software/emacs/manual/html_node/elisp/File-Notifications.html][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 [[https://www.gnu.org/software/auctex/][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.

+BEGIN_SRC emacs-lisp

(add-hook 'TeX-after-compilation-finished-functions #'TeX-revert-document-buffer)

+END_SRC

** Some keybindings

Navigation
Scroll Up / Down by page-full ~space~ / ~backspace~
Scroll Up / Down by line ~C-n~ / ~C-b~
Scroll Right / Left ~C-f~ / ~C-b~
Top of Page / Bottom of 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 ~B~ / ~F~
Display Outline ~o~
Jump to Section from Outline ~RETURN~
Jump to Page ~M-g g~
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
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~
Add and edit annotations via Mouse selection and left-click context menu
Syncing with Auctex
jump to PDF location from source ~C-c C-g~
jump source location from PDF ~C-mouse-1~
Miscellaneous
Refresh File (e.g., after recompiling source) ~g~
Print File ~C-c C-p~

Local Variables:

mode: org

End:

pdf-tools open issues Ask a question     (View All Issues)
  • almost 3 years Lag when selecting words/sentences
  • almost 3 years Hide password when using sudo
  • about 3 years Make pdf-tools integrate with window-layout packages
  • about 3 years Two Column View (follow-mode)
  • about 3 years PDF file opens but the buffer stays blank
  • over 3 years Mouse selection wrong when using trim margins
  • over 3 years Build fails on OSX because uname -o is not supported
  • over 3 years invalid-function pdf-view-current-page ?
  • over 3 years Symbol's function definition is void: pdf-occur-global-minor-mode
  • over 3 years "Forgets" annotations
  • over 3 years Display page numbers?
  • over 3 years Remember pdf position *within* sessions
  • over 3 years How to save/open password encrypted pdf files?
  • over 3 years Does not build with OpenBSD make
  • over 3 years auto-refresh of pdf buffer after LaTeX
  • almost 4 years memory consumption and cache not releasing memory
  • almost 4 years Commands to move to next and previous headings in pdf-view-mode
  • almost 4 years pdfview buffer isn't reverted when exporting from org
  • almost 4 years Select texts using keyboard
  • almost 4 years Image relief feature is broken
  • almost 4 years Remote buffer do not revert properly
  • almost 4 years Problem when displaying different buffers in same window
  • almost 4 years Add ability to change default font used for rendering
  • almost 4 years package epdfinfo separately
  • almost 4 years inline notes
  • almost 4 years extract embedded images
  • almost 4 years Arrow tooltip does not display on Mac
  • almost 4 years make use of actual annotation UID stored in the pdf document
  • about 4 years Implement push/pop mark feature
  • about 4 years Slice needs to be recomputed when the pdf buffer is refreshed
pdf-tools open pull requests (View All Pulls)
  • Add documentation and "TODO" comments.
  • Improved ci
  • Automate the build on FreeBSD
  • Make pdf-view-scale-reset use the default zoom.
  • add function pdf-sync-backward-isearch-match in issue#29
  • Enable building under Windows
  • remove third-party libraries
  • Ask user for a password if PDF is encrypted
  • Add Windows compilation instructions
  • Allow page change with C-v and M-v
  • Add `setenv` example for macOS.
  • Add info about compiling on Centos
  • sync backward the current match of pdf-isearch to LaTeX source
  • Use user-error instead of error in pdf-view-goto-page
  • Add Appvyeor build
  • Use clang when building the server with nix-shell
  • Note that you need to install Cask on OS X.
  • Check for NixOS after macOS
  • increase discoverability of auto-trim margins minor mode
  • Improve signaling in case of user errors
  • Add and use pdf-view-catch-error-when-interactive
  • Enable building in OpenBSD
  • Readme Changes
  • Make outline-regexp buffer-local in pdf-outline-buffer-mode
  • Fixing Windows Compile Issue
pdf-tools questions on Stackoverflow (View All Questions)
  • Convert pdf document to jpeg using LEADTOOLS and PDF-TOOLS
  • Pdf tools to analyze pdf attributes
  • Why are my 3rd-party HTML to PDF tools not recognized in Drupal 6 using Print module?
  • suggestion for a couple of pdf tools
pdf-tools list of languages used
Other projects in Emacs Lisp