The Emacs text editor can be extended with a plethora of packages. One of these packages is PDF Tools which allows PDF files to be rendered and viewed from an Emacs buffer. PDF Tools depends on a server program to perform the rendering step. In this article, the server program is installed on Windows and the Emacs package is configured to use this program.

Note: the PDF Tools package provides the (pdf-tools-install) command to install and configure the server component. This command, however, builds the dependencies from scratch. It therefore has a dependency on Clang which may not be available on your system. This article therefore presents an alternative by using pre-built binaries.

Prerequisites

The requirements are as follows:

  • A recent installation of Windows.
  • An Emacs installation with a configured package manager, e.g. package.el or straight.el.
  • A way to install MSYS2, either directly or via a package manager like Scoop.

Steps

Step 1: Install MSYS2 and the PDF Tools server component

The MSYS2 package mingw-w64-x86_64-emacs-pdf-tools-server contains the server component required by PDF Tools. In order to download this package, an installation of MSYS2 is required.

If an installation of MSYS2 is not yet available, it can be installed by downloading and executing the installer from the MSYS2 website, or through Scoop with the following command:

scoop install msys2

This will cause MSYS2 to be installed:

scoop install msys2
Installing 'msys2' (2023-01-27) [64bit] from main bucket
Loading msys2-base-x86_64-20230127.tar.xz from cache
Checking hash of msys2-base-x86_64-20230127.tar.xz ... ok.
Extracting msys2-base-x86_64-20230127.tar.xz ... done.
Linking ~\scoop\apps\msys2\current => ~\scoop\apps\msys2\2023-01-27
Creating shim for 'msys2'.
Creating shim for 'mingw'.
Creating shim for 'mingw32'.
Creating shim for 'mingw64'.
Creating shim for 'clang32'.
Creating shim for 'clang64'.
Creating shim for 'ucrt64'.
Creating shortcut for MSYS2 (msys2.exe)
Creating shortcut for MinGW32 (mingw32.exe)
Creating shortcut for MinGW64 (mingw64.exe)
Creating shortcut for Clang32 (clang32.exe)
Creating shortcut for Clang64 (clang64.exe)
Creating shortcut for UCRT64 (ucrt64.exe)
Persisting home
'msys2' (2023-01-27) was installed successfully!
Notes
-----
Please run 'msys2' now for the MSYS2 setup to complete!

The msys2 executable is now available via the command line. Scoop has added it to the path automatically. Run this executable to finish installation:

msys2

You will receive a prompt stating "This is the first start of MSYS2. You MUST restart shell to apply necessary actions.", do so by typing exit, after which MSYS2 can be opened again with the msys2 command.

Type the following command into the MSYS2 shell to install the PDF Tools server component:

pacman -S mingw-w64-x86_64-emacs-pdf-tools-server

If the component is not yet installed, a prompt similar to the one below is shown. Answer with y to install the component.

resolving dependencies...
looking for conflicting packages...
warning: dependency cycle detected:
warning: mingw-w64-x86_64-harfbuzz will be installed before its mingw-w64-x86_64-freetype dependency
warning: dependency cycle detected:
warning: mingw-w64-x86_64-libwebp will be installed before its mingw-w64-x86_64-libtiff dependency

Packages (59) mingw-w64-x86_64-brotli-1.0.9-5  mingw-w64-x86_64-bzip2-1.0.8-2  mingw-w64-x86_64-c-ares-1.18.1-2
              mingw-w64-x86_64-ca-certificates-20211016-4  mingw-w64-x86_64-cairo-1.17.6-3
              mingw-w64-x86_64-curl-7.87.0-3  mingw-w64-x86_64-expat-2.5.0-1  mingw-w64-x86_64-fontconfig-2.14.1-1
              mingw-w64-x86_64-freetype-2.12.1-1  mingw-w64-x86_64-gcc-libs-12.2.0-10
              mingw-w64-x86_64-gettext-0.21.1-1  mingw-w64-x86_64-giflib-5.2.1-3  mingw-w64-x86_64-glib2-2.74.5-1
              mingw-w64-x86_64-graphite2-1.3.14-2  mingw-w64-x86_64-harfbuzz-6.0.0-1  mingw-w64-x86_64-icu-72.1-1
              mingw-w64-x86_64-jbigkit-2.1-4  mingw-w64-x86_64-lcms2-2.14-2  mingw-w64-x86_64-lerc-4.0.0-1
              mingw-w64-x86_64-libdeflate-1.17-2  mingw-w64-x86_64-libffi-3.4.4-1  mingw-w64-x86_64-libiconv-1.17-1
              mingw-w64-x86_64-libidn2-2.3.3-1  mingw-w64-x86_64-libjpeg-turbo-2.1.4-1
              mingw-w64-x86_64-libpng-1.6.39-1  mingw-w64-x86_64-libpsl-0.21.2-3  mingw-w64-x86_64-libssh2-1.10.0-2
              mingw-w64-x86_64-libsystre-1.0.1-4  mingw-w64-x86_64-libtasn1-4.19.0-1  mingw-w64-x86_64-libtiff-4.5.0-1
              mingw-w64-x86_64-libtre-git-r128.6fb7206-2  mingw-w64-x86_64-libunistring-1.0-1
              mingw-w64-x86_64-libwebp-1.3.0-2  mingw-w64-x86_64-libwinpthread-git-10.0.0.r202.g4359b3570-1
              mingw-w64-x86_64-lzo2-2.10-2  mingw-w64-x86_64-mpdecimal-2.5.1-1  mingw-w64-x86_64-ncurses-6.4-1
              mingw-w64-x86_64-nghttp2-1.51.0-1  mingw-w64-x86_64-nspr-4.35-1  mingw-w64-x86_64-nss-3.83-1
              mingw-w64-x86_64-openjpeg2-2.5.0-4  mingw-w64-x86_64-openssl-3.0.7-3  mingw-w64-x86_64-p11-kit-0.24.1-3
              mingw-w64-x86_64-pcre2-10.42-1  mingw-w64-x86_64-pixman-0.42.2-1  mingw-w64-x86_64-poppler-22.12.0-3
              mingw-w64-x86_64-poppler-data-0.4.11-1  mingw-w64-x86_64-python-3.10.9-2
              mingw-w64-x86_64-readline-8.2.001-6  mingw-w64-x86_64-sqlite3-3.40.1-1  mingw-w64-x86_64-tcl-8.6.12-1
              mingw-w64-x86_64-termcap-1.3.1-6  mingw-w64-x86_64-tk-8.6.12-1  mingw-w64-x86_64-tzdata-2022g-1
              mingw-w64-x86_64-wineditline-2.205-3  mingw-w64-x86_64-xz-5.2.9-1  mingw-w64-x86_64-zlib-1.2.13-2
              mingw-w64-x86_64-zstd-1.5.2-2  mingw-w64-x86_64-emacs-pdf-tools-server-1.0.0-1

Total Download Size:    90.04 MiB
Total Installed Size:  501.08 MiB

:: Proceed with installation? [Y/n]

The component is installed when this process is finished. Emacs can now be configured.

Step 2: Install the PDF Tools package and configure Emacs

The PDF Tools package requires two variables to be configured:

  • The environment variable PATH, to access the executables provided by MSYS2.
  • The Emacs variable pdf-info-epdfinfo-program, which contains the path to the epdfinfo.exe executable provided by MSYS2.

Determine the values for these variables for your installation. If Scoop has been used, the path is as follows:

C:\Users\<username>\scoop\apps\msys2\current\mingw64\bin

E.g.:

C:\Users\ferdy\scoop\apps\msys2\current\mingw64\bin

Copy the following expression to your init.el file and change the paths to match your installation. Note that the \ character needs to be escaped by prepending it with another \.

(use-package pdf-tools
  :init
  (setenv "PATH" (concat "C:\\Users\\ferdy\\scoop\\apps\\msys2\\current\\mingw64\\bin" ";" (getenv "PATH")))
  (pdf-tools-install)
  :custom
  (pdf-info-epdfinfo-program "C:\\Users\\ferdy\\scoop\\apps\\msys2\\current\\mingw64\\bin\\epdfinfo.exe"))

This expression performs the following actions:

  • Install the pdf-tools package.
  • Append the MSYS2 folder to the PATH environment variable.
  • Evaluate (pdf-tools-install), which ensures (amongst others) that PDF files are opened in pdf-view-mode.
  • Set the value of the pdf-info-epdfinfo-program variable to the newly installed epfdinfo.exe executable.

Evaluate the expression (or restart Emacs) to download, install and configure the pdf-tools package. When PDF files are now opened, e.g. through (find-file) or via dired, they will now be rendered and can be viewed straight from the Emacs buffer.

Step 3: Perform updates

After updating the pdf-tools package, you may encounter the following prompt when starting Emacs:

Need to (re)build the epdfinfo program, do it now ? (y or n)

When this happens, answer with n. (As the pdf-tools package will attempt to compile the epdfinfo binary from source when answering with y.) We will perform the upgrade ourselves.

Open a new MSYS2 prompt with:

msys2

Update installed packages with: 

pacman -Syu

If the message To complete this update all MSYS2 processes including this terminal will be closed. Confirm to proceed [Y/n] is shown, answer with Y. Afterwards, open another MSYS2 prompt and perform the upgrade command again. The remaining packages will now be updated.

If the mingw-w64-x86_64-emacs-pdf-tools-server package is not listed when upgrading packages, perform the upgrade manually by executing the following command:

pacman -S mingw-w64-x86_64-emacs-pdf-tools-server

The server component is now updated to the latest version. You might need to restart Emacs or execute the (pdftools-install) expression to ensure the latest server package is used.

Troubleshooting

If PDF files are not rendered, check the following:

  • Ensure that the value of the variable pdf-info-epdfinfo-program contains a path to the epdfinfo.exe executable. This can be checked by evaluating the expression: (describe-variable pdf-info-epdfinfo-program).
  • Run the expression (pdf-info-check-epdfinfo) to verify that a connection can be made to the server component. It should produce the message "The epdfinfo program appears to be working."; if not, a connection could not be made.