Installation

PyMuPDF can be installed from sources as follows, or from wheels, see Option 2: Install from Binaries.

It has no mandatory external dependencies apart from the standard library. A handful of nice-to-have methods are available only if certain packages are installed:

Option 1: Install from Sources

This is a three-step process.

Step 1: Download PyMuPDF

Download the sources from https://pypi.org/project/PyMuPDF/#files and decompress them.

Step 2: Download and Generate MuPDF

Download mupdf-x.xx.x-source.tar.gz from Mupdf and unzip / decompress it. Make sure to download the (sub-) version for which PyMuPDF has stated its compatibility.

Note

The latest MuPDF development sources are available on https://github.com/ArtifexSoftware/mupdf – this is not what you want here.

Applying any Changes and Hot Fixes to MuPDF Sources

On occasion, vital hot fixes or functional enhancements must be applied to MuPDF sources before it is generated.

Any such files are contained in the fitz directory of the PyMuPDF homepage – their names all start with an underscore “_”. Currently (v1.16.x), these files and their copy destinations are the following:

  • _config.h(Optional) PyMuPDF’s configuration to control the binary file size. Copy-rename it to /include/mupdf/fitz/config.h. This reduces the size of the PyMuPDF binary extension module to around 11 MB. If omitting this change, that size will be over 30 MB – without impacting functionality.

Generate MuPDF

The MuPDF source includes generation procedures / makefiles for numerous platforms. For Windows platforms, Visual Studio solution and project definitions are provided.

PyMuPDF’s homepage contains additional details and hints.

Step 3: Build / Setup PyMuPDF

Adjust the setup.py script as necessary. E.g. make sure that:

  • the include directories are correctly set in sync with your directory structure

  • the object code libraries are correctly defined

Now perform a python setup.py install.

Note

You can also install from sources of the Github repository. These do not contain the pre-generated files fitz.py or fitz_wrap.c, which instead are generated by the installation script setup.py. To use it, SWIG must be installed on your system.

Option 2: Install from Binaries

You can install PyMuPDF from Python wheels. Wheels are self-contained, i.e. you will not need any other software nor download / install MuPDF to run PyMuPDF scripts. This installation option is available for all MS Windows and the most popular 64-bit Mac OSX and Linux platforms for Python versions 3.6 through 3.9. Since version 1.18.13, Linux ARM 64-bit architectures are also supported, and since version 1.18.15, Mac OSX universal architectures, too. Windows binaries are provided for Python 64-bit and 32-bit versions.

Overview of wheel names (PyMuPDF version is x.xx.xx):

PyMuPDF-x.xx.xx-cp36-cp36m-macosx_10_9_x86_64.whl
PyMuPDF-x.xx.xx-cp36-cp36m-manylinux_2_12_x86_64.manylinux2010_x86_64.whl
PyMuPDF-x.xx.xx-cp36-cp36m-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
PyMuPDF-x.xx.xx-cp36-cp36m-win_amd64.whl
PyMuPDF-x.xx.xx-cp36-cp36m-win32.whl
PyMuPDF-x.xx.xx-cp37-cp37m-macosx_10_9_x86_64.whl
PyMuPDF-x.xx.xx-cp37-cp37m-manylinux_2_12_x86_64.manylinux2010_x86_64.whl
PyMuPDF-x.xx.xx-cp37-cp37m-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
PyMuPDF-x.xx.xx-cp37-cp37m-win_amd64.whl
PyMuPDF-x.xx.xx-cp37-cp37m-win32.whl
PyMuPDF-x.xx.xx-cp38-cp38-macosx_10_9_x86_64.whl
PyMuPDF-x.xx.xx-cp38-cp38-manylinux_2_12_x86_64.manylinux2010_x86_64.whl
PyMuPDF-x.xx.xx-cp38-cp38-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
PyMuPDF-x.xx.xx-cp38-cp38-manylinux2010_x86_64.whl
PyMuPDF-x.xx.xx-cp38-cp38-win_amd64.whl
PyMuPDF-x.xx.xx-cp38-cp38-win32.whl
PyMuPDF-x.xx.xx-cp39-cp39-macosx_10_9_x86_64.whl
PyMuPDF-x.xx.xx-cp39-cp39-manylinux_2_12_x86_64.manylinux2010_x86_64.whl
PyMuPDF-x.xx.xx-cp39-cp39-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
PyMuPDF-x.xx.xx-cp39-cp39-win_amd64.whl
PyMuPDF-x.xx.xx-cp39-cp39-win32.whl

Older versions can be found in the releases directory of our home page https://github.com/pymupdf/PyMuPDF/releases.

Please always make sure you have updated your PIP to the current version and always invoke pip as a module within the right Python version python -m pip install ....