Installation

Basic installation

pikepdf latest released version on PyPI

Most users on Linux, macOS or Windows with x64 systems should use pip to install pikepdf in their current Python environment (such as your project’s virtual environment).

pip install pikepdf

Use pip install --user pikepdf to install the package for the current user only. Use pip install pikepdf to install to a virtual environment.

Linux users: If you have an older version of pip, such as the one that ships with Ubuntu 18.04, this command will attempt to compile the project instead of installing the wheel. If you want to get the binary wheel, upgrade pip with:

wget https://bootstrap.pypa.io/get-pip.py && python3 get-pip.py
pip --version  # should be 20.0 or newer
pip install pikepdf

Binary wheel availability

Python binary wheel availability

3.7

3.8

3.9

3.10

PyPy 3.7

macOS Intel

macOS Apple Silicon

✅*

Windows 64-bit

Windows 32-bit

manylinux2014 64-bit

manylinux2014 32-bit

musllinux 64-bit

musllinux 32-bit

* Apple Silicon is supported on a best-effort by manually uploading. These releases sometimes come a few days later.

Binary wheels should work on most systems, provided a recent version of pip is used to install them. Old versions of pip, especially before 20.0, may fail to check appropriate versions.

macOS 10.14 or newer is typically required for binary wheels. Older versions may work if compiled from source.

Windows 7 or newer is required. Windows wheels include a recent copy of libqpdf.

Most Linux distributions support manylinux2010, with the notable except of Alpine Linux, and older Linux distributions that do not have C++17-capable compilers. The Linux wheels include recent copies of libqpdf, libjpeg, and zlib.

Platform support

Some platforms include versions of pikepdf that are distributed by the system package manager (such as apt). These versions may lag behind the version distributed with PyPI, but may be convenient for users that cannot use binary wheels.

Bento box containing sushi

Packaged fish.

Package status for python:pikepdf

Debian, Ubuntu and other APT-based distributions

apt install pikepdf

Fedora

Fedora Rawhide

dnf install python-pikepdf

Alpine Linux

Alpine Linux Edge

apk add py3-pikepdf

Installing on FreeBSD

pkg install py38-pikepdf

To attempt a manual install, try something like:

pkg install python3 py38-lxml py38-pip py38-pybind11 qpdf
pip install --user pikepdf

This procedure is known to work on FreeBSD 11.3, 12.0, 12.1-RELEASE and 13.0-CURRENT. It has not been tested on other versions.

Building from source

Requirements

pikepdf requires:

  • a C++17 compliant compiler - roughly GCC 7+, clang 6+, or MSVC 19+

  • pybind11

  • libqpdf 10.3.1 or higher from the QPDF project.

On Linux the library and headers for libqpdf must be installed because pikepdf compiles code against it and links to it.

Check Repology for QPDF to see if a recent version of QPDF is available for your platform. Otherwise you must build QPDF from source. (Consider using the binary wheels, which bundle the required version of libqpdf.)

Compiling with GCC or Clang

  • clone this repository

  • install libjpeg, zlib and libqpdf on your platform, including headers

  • pip install .

Note

pikepdf should be built with the same compiler and linker as libqpdf; to be precise both must use the same C++ ABI. On some platforms, setup.py may not pick the correct compiler so one may need to set environment variables CC and CXX to redirect it. If the wrong compiler is selected, import pikepdf._qpdf will throw an ImportError about a missing symbol.

On Windows (requires Visual Studio 2015)

pikepdf requires a C++17 compliant compiler (i.e. Visual Studio 2015 on Windows). See our continuous integration build script in .appveyor.yml for detailed and current instructions. Or use the wheels which save this pain.

These instructions require the precompiled binary qpdf.dll. See the QPDF documentation if you also need to build this DLL from source. Both should be built with the same compiler. You may not mix and match MinGW and Visual C++ for example.

Running a regular pip install command will detect the version of the compiler used to build Python and attempt to build the extension with it. We must force the use of Visual Studio 2015.

  1. Clone this repository.

  2. In a command prompt, run:

    %VS140COMNTOOLS%\..\..\VC\vcvarsall.bat" x64
    set DISTUTILS_USE_SDK=1
    set MSSdk=1
    
  3. Download qpdf-10.3.2-bin-msvc64.zip from the QPDF releases page.

  4. Extract bin\*.dll (all the DLLs, both QPDF’s and the Microsoft Visual C++ Runtime library) from the zip file above, and copy it to the src/pikepdf folder in the repository.

  5. Run pip install . in the root directory of the repository.

Note

The user compiling pikepdf to must have registry editing rights on the machine to be able to run the vcvarsall.bat script.

Building against a QPDF source tree

Follow these steps to build pikepdf against a different version of QPDF, rather than the one provided with your operating system. This may be useful if you need a more recent version of QPDF than your operating system package manager provides, and you do not want to use Python wheels.

  • Set the environment variable QPDF_SOURCE_TREE to the location of the QPDF source tree.

  • Build QPDF, by running make. Refer to the QPDF installation instructions for further options and details.

  • On Linux, modify LD_LIBRARY_PATH, prepending the path where the QPDF build produces libqpdfXX.so. This might be something like $QPDF_SOURCE_TREE/.build/libs/libqpdfXX.so. On macOS, locate the equivalent variable is DYLD_LIBRARY_PATH. On Windows, no action is needed. Generally, what you are doing here is telling the runtime dynamic linker to use the custom compiled version of QPDF instead of the system version.

  • Build pikepdf. On Windows, locate the QPDF .dll files and copy them into the folder alongside the file named _qpdf*.dll.

Note that the Python wheels for pikepdf currently compile their own version of QPDF and several of its dependencies to ensure the wheels have the latest version. You can also refer to the GitHub Actions YAML files for build steps.

Building against a custom install of QPDF to /usr/local/lib

If you have previously installed a QPDF from source to /usr/local/lib on a POSIX platform, and you try to build pikepdf from source, it will prefer the operating system version of QPDF installed at /usr/lib. Since pikepdf strongly prefers recent versions of QPDF, you may want to use a more current version.

From a Git checkout of the pikepdf source tree, run:

env LDFLAGS='-L/usr/local/lib' CFLAGS='-I/usr/local/include/qpdf' pip install .

Building the documentation

Documentation is generated using Sphinx and you are currently reading it. To regenerate it:

pip install pikepdf[docs]
cd docs
make html

PyPy3 support

PyPy3 3.7 is currently supported, these being the latest versions of PyPy as of this writing. Windows PyPy wheels are not supported because cibuildwheel does not support Windows 64-bit PyPy. We have not checked if source builds work.

PyPy3 is not more performant than CPython for pikepdf, because the core of pikepdf is already written in C++. The benefit is for applications that want to use PyPy for improved performance of native Python and also want to use pikepdf.