pdf-tools includes pdf-view-mode which offers several features not present in doc-view-mode (see end of question).

Can pdf-view-mode be used as a replacement for doc-view-mode generally, or does it have to be "tool" by tool?

In either case, is it necessary to edit emacs source to use pdf-tools in gnus, eww and orgmode or are their system-wide settings that can be employed?

--- Features of pdf-tools here for convenience; see github site for details ---

  1. Seems faster than doc-view
  2. Resolution usually better since not being rendered as a png
  3. Nice search, and can even search for all occurrences of a phrase
  4. Can add text annotations, and highlighting, underlining, and the like
  5. Can create imenus for pdf parts
  6. Can treat several pdfs as a single "virtual" pdf
  7. Can integrate with latex to see latex source and pdf side by side and jump from one to the other at the equivalent locations (e.g. select \section{A section} in LaTeX and got that section in pdf.
  • See here for a related discussion which likely includes the answer to your questions.
    – tmalsburg
    Jan 19, 2016 at 18:40
  • Gnus may be a special case? See: lists.gnu.org/archive/html/help-gnu-emacs/2015-02/msg00438.html
    – Brian Z
    Jan 19, 2016 at 19:20
  • You might need to reword your question away from the dreaded 'best-practices', which some folks assume means answers will be primarily opinion-based. I seem to recall gnus is a special case here, and you will need to add appropriate config to .mailcap. If your question isn't closed before I get home, I'll dig up my config for you.
    – Tyler
    Jan 19, 2016 at 20:35
  • 2
    Gnus uses mailcap to figure out what applications to open attachments with. If you have Emacs configured to open pdf files with pdf-tools, you need to add the line application/pdf; emacsclient %s to .mailcap, and start the Emacs edit-server: invoke Emacs as emacs --daemon, or add (server-start) to your .emacs.
    – Tyler
    Jan 20, 2016 at 3:07
  • Thanks. That works, and after that this works for org. (set 'org-file-apps '((auto-mode . emacs) ... ("\\.pdf\\'" . default))) Jan 20, 2016 at 11:25

1 Answer 1


Switching from docview to pdf-tools happens 'automatically' when you install pdf-tools. Once you've done this, any time Emacs tries to open a pdf in Emacs, it will use pdf-tools. However, some packages will call out to the operating system, or use different config within Emacs, to decide if they should use Emacs or another program to open a pdf. So there is some 'tool-by-tool' configuration required to get all Emacs packages to use pdf-tools.

If you want your pdfs opened in the same instance of Emacs, you need to have it running in daemon mode (i.e., start it with emacs --daemon), or call (server-start) in your init so that emacsclient will work.

Org-mode links

Out of the box, org-mode doesn't know about pdf-tools. However, you can add support for opening org links to pdf files with org-pdfview, which is available as a package on MELPA. Once it's installed, you can activate it with the following code in your .emacs:

(eval-after-load 'org '(require 'org-pdfview))

(add-to-list 'org-file-apps 
             '("\\.pdf\\'" . (lambda (file link)
                                     (org-pdfview-open link))))

Doing this will provide a new completion target for adding links via C-c C-l, pdfview:, with support for jumping to specific pages. Full links use the format:

[[pdfview:/path/to/myfile.pdf::42][My file Description]]

Interleave Mode & PDF annotations

Interleave mode provides support for presenting "your PDF side by side with an Org Mode buffer with your notes." This is an alternative to using the annotations embedded in a pdf (which you can do with pdf-tools). Instead, you end up with an org-mode file with all your annotations, which links to the page in the pdf that the annotations are associated with.


As I mentioned in my comment, gnus uses mailcap to open attachments. To configure this, you need the following in your .mailcap file:

application/pdf; emacsclient %s


EWW also uses mailcap, so modify your .mailcap file as per Gnus above.


For AucTeX, there are a number of relevant options:

  • viewers are specified via the variable TeX-view-program-selection: find the entry for output-pdf and select "PDF Tools" for the value.
  • to use SyncTex, you need to:
    • set TeX-source-correlate-mode, either interactively by calling that function via M-x, or by setting the variable permanently via M-x customize-variable.
    • make sure TeX-source-correlate-method includes (pdf . synctex)

With this in place, from your tex source file C-c C-g should display the corresponding section of the pdf.


Customize the variable ess-pdf-viewer-pref to emacsclient.


On Linux, some packages will call the external program xdg-open to open pdf files. This will use your system-wide settings to determine which program to use. This is a system-wide change, so other programs will send pdf documents to Emacs when you've set this up. So if you don't want, e.g., Firefox, to do this, you won't want to make these changes.

To set emacsclient to open pdfs system-wide via xdg-open:

  • create a file in ~/.local/share/applications/emacsclient.desktop with the contents:

[Desktop Entry]
Name=Emacs Client
Exec=emacsclient %u

  • from the command line, issue:

xdg-mime default emacsclient.desktop application/pdf

You can test that this worked with xdg-open your-document.pdf - it should open your-document.pdf in Emacs.


w3m first checks the variable w3m-doc-view-content-types, and if it sees "application/pdf" there, it will open pdfs in doc-view. This is a customizable variable, so remove the "application/pdf" entry using the customization interface.

Without an entry in w3m-doc-view-content-types, w3m next checks the variable w3m-content-type-alist for entries that match "application/pdf". Customize the entry to read

[INS] [DEL] Type: application/pdf
  Regexp: ( ) Not specified
          (*) String: \.pdf\'
  Viewer: ( ) Not specified
          (*) External viewer:
                Command: emacsclient
                  [INS] [DEL] file

You could also use an emacs function (presumably find-file or similar), rather than an external call to emacsclient, but I couldn't figure out the syntax for that.

  • However w3m in emacs still uses docview. Any advice how to fix that one? Mar 11, 2017 at 12:55
  • see the updated answer
    – Tyler
    Mar 13, 2017 at 19:00
  • Can I link from org-mode to a particular annotation in the PDF file? Aug 14, 2017 at 8:22
  • 1
    @AlwaysLearning not that I'm aware of. Interleave mode provides support for recording annotations in a separate, linked, org-mode file. I'll update the answer
    – Tyler
    Aug 14, 2017 at 13:46

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.