How to configure Emacs and AUCTeX to work with a PDF viewer

I’m writing my thesis in LaTeX, using Emacs and the AUCTeX environment. Today I managed to configure AUCTeX to generate PDFs (that’s the easy part), but also to correlate the LaTeX source and the PDF file (that’s way trickier). As it was painful to make it work, here is an easy how-to which only uses Emacs’ graphical interface.

Please note that this procedure works as is for AUCTeX 11.86 and TeX Live 2009; it needs to be amended in case you have :

Here is the procedure :

  1. Open a tex file with Emacs.
  2. In the LaTeX menu, go to “Customize AUCTeX” and click on “Extend this menu”.
  3. Then go again to LaTeX, “Customize AUCTeX”, go to the “Tex Command” submenu and click on the included “Tex command” item.
  4. You are now in the “Tex command group” configuration buffer, scroll down until you reach “Tex Pdf Mode”. Its value is off (nil), click on the “Toggle” button to activate this mode. Click on the “State” button and select “Save for Future Sessions”. AUCTeX will now compile your tex file using pdflatex and produce a pdf output. That was the easy part.
  5. Still in the “Tex command group” configuration buffer, scroll all the way down and click on the special item called “Tex View”. In the “Tex view group” buffer, you have two things to do : activate the correlate mode between the PDF and the tex file, and declare a PDF viewer which can read these correlations. At the moment, only Okular does the trick in Debian Sid.
  6. To activate the correlate mode :
    1. item “Tex Source Correlate Method”, click on the “Value Menu” button and select “synctex” and save for future sessions,
    2. item “Tex Source Correlate Start Server”, select “Always” and save,
    3. item “Tex Source Correlate Mode”, toggle it on and save.
  7. To set Okular as the default PDF viewer :
    1. item “Tex View Program List”, right arrow, then button “INS”
      1. name: Okular
      2. choice: Command
      3. command: okular –unique %o#src:%n%b
    2. item “Tex View Program Selection”, right arrow, then “INS”
      1. choice: Single predicate
      2. single predicate: output-pdf
      3. viewer: Okular (if you just added Okular to the Tex View Program List, this choice might not appear, but if you restart Emacs it will show up)
  8. Save both for future sessions. Close Emacs, re-open your tex file and voilà.
  9. To configure Okular: in the Okular window, go to the “Settings” menu, item “Configure Okular”, “Editor”, select Emacs client.

To use Forward search from Emacs to Okular, just hit Ctrl+C Ctrl+V to call the viewer. Okular will center its display on the intended line of the pdf.

To use Inverse search from Okular to Emacs, just hit Shift+Left mouse click on the pdf. Emacs will come up and position the cursor at the intended line of the TeX source.

I started using information from bleedingmind, lost hours and was finally saved by Luis Finotti’s post.

AUCTeX can also display the compilation errors in Emacs and point exactly to the wrong part of your source code. To enable this or fix its behaviour (e.g. when it opens a blank buffer strangely named “Debian” in place of your TeX source), you might need to set up TeX to produce file:line:error style messages. To do that,

  • as a root or sudo user,
  • open /etc/texmf/texmf.d/95NonPath.cnf (on Debian),
  • change “file_line_error_style = f” to “file_line_error_style = t” and save,
  • run “update-texmf” which regenerates /etc/texmf/texmf.cnf from the files in /etc/texmf/texmf.d/ .

Figuring the cause and finding the relevant information online took me two terrible hours of sweat and anger at a critical time. Now I’m happily back to writing.

43 thoughts on “How to configure Emacs and AUCTeX to work with a PDF viewer

  1. Thanks! After installing auctex from testing (I’m otherwise on squeeze) I think I am now almost set up. Still looking for a way to have okular show a bounding box around the area I selected in emacs (just like xdvi does),
    and I can’t seem to find how to get the inverse search on Ctrl+Left instead of Shift+Left.

    • You’re welcome too.
      I see what your two requirements mean, but I cannot find any working solution.
      For your first feature, having a peek at the patch for evince could help.

      If you succeed on those two some day, let us know !

  2. Ok. Just as mine is after submitting the comment. Stupid artificial intelligence 🙂

    7.A.III should be
    command: okular ––unique %o#src:%n%b

  3. Hi your instruction was very useful for me! Thanks!
    I noticed that solution with errors pointing works when I compile to dvi but it does not work if I compile to pdf.
    All the best

  4. Thank you a lot — your post is extremely helpful for me! Nevertheless I’m experiencing some troubles: when I hit the pdf-Button Okular opens twice–in one window it produces the pdf as it should be, in the second window it says that the specific tex-file could not be opened!

  5. Hello,
    I am trying to add a “pdfviewer” command which looks like

    (add-to-list ‘TeX-command-list
    (list “pdfviewer” “sumatraPDF %s.pdf”
    ‘TeX-run-command nil t))
    Emacs can fine sumatraPDF. But it looks that the option %s.pdf is wrong. With that, Emacs tries the command sumatraPDF “filename”.pdf instead of sumatraPDF filename.pdf. With this extra “”, sumatraPDF cannot find the right file name. I also tried %o, but in Latex-Mode, %o means filename.dvi by default. Maybe you know something that can help me out here. There should be an option that represents filename.pdf. But I have no idea what it is and how to find it.

  6. Je suis en train de découvrir emacs et je dois dire que j’étais sur le point de l’abandonner quand je suis tombé sur vos explications.

    Merci beaucoup !


  7. Hello,

    thank you very much for this usefull hint. I got only a small problem with this: after formatting a file and opening it with okular, I got two and sometimes more okular windows, but only one is showing the correct file. For the other windows I got an error message: unable to open specified file.
    Everything else is working fine. Has anyone an idea how to fix this?



  8. Hello thanks for sharing!

    I’ve got a question on your 9th step: To configure Okular: Settings, Configure Okular, Editor, select Emacs client.

    I don’t know how to do it… How can I get into the Settings? I’m quite new in auctex and kinda fool in this setting things..

    Look forward to any piece of suggestions. Thanks!!

    • Hi Lisa,
      Step 9 refers to Okular’s own configuration.
      You will find this “settings” menu inside Okular.
      I will edit the post to make it clearer.

  9. Merci beaucoup! Fantastic help page. Initially, after following your directions, emacs hung upon invoking view pdf. But that was fixed by deleting the reference to Evince in the Tex View Program List.

  10. Thank you for writing up this piece. Being an Emacs newbie that I am, I learnt quite a bit from this very clearly written post.

    Thank you so much!

  11. Thanks a lot for this post! It helped me too.

    I think you should update the “TeX View Program List command” with the TexLive 2011 version posted by nabla, for those of us with more recent installation.
    okular –unique %o#src:%n`pwd`/./%b
    With that addition, your guide works great in Kubuntu 12.10.

  12. Thanks a lot! Worked perferctly, except for the copy-and-paste-issue, which was resolved after reading the comments… First emacs-tweak that worked at the first try.

    Thanks again!

  13. Salut, Bonjour,

    Merci beaucoup pour ce major effort. SVP, je m’adresse à vous pour me donner un piste d’installation de Okular sous Mac. J’ai bien fouillé sur google mais en vain. D’ailleurs même j’ai pas trouvé ce logiciel. Merci pour votre aide

  14. Thank You so much Mathieu. This helped me a lot. Only trouble was regarding the command for okular. That got fixed due to the comment from nabla on August 25, 2011 at 8:47 am. It is a great post, you have explained things very very clearly. Thanks once again… 🙂

  15. Pingback: Configuring Mutt and Emacs with AUCTex | Coherent Musings

Leave a Reply

Your email address will not be published. Required fields are marked *