Installation
=============
PyMuPDF can be installed from sources as follows or from wheels, see :ref:`InstallBinary`.

.. _InstallSource:

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 <https://mupdf.com/downloads/archive>`_ 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 <https://github.com/pymupdf/PyMuPDF/tree/master/fitz>`_ -- their names all start with an underscore *"_"*. Currently (v1.16.x), these files and their copy destinations are the following:

* *_config.h* -- PyMuPDF's configuration to control the binary file size and the inclusion of MuPDF features, see next section. This file must renamed and replace MuPDF file */include/mupdf/fitz/config.h*. This file controls the size of the PyMuPDF binary by cutting away unneeded fonts from MuPDF.

**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 <https://github.com/pymupdf/PyMuPDF/>`_ contains additional details and hints.

Step 3: Build / Setup PyMuPDF
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Adjust the setup.py script as necessary. E.g. make sure that:

  * the include directory is 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 the 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 <https://www.swig.org/>`_ must be installed on your system.


.. _InstallBinary:

Option 2: Install from Binaries
--------------------------------
You can install PyMuPDF from Python wheels. The 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 2.7 and 3.5 through 3.8.
Windows binaries are provided for Python **32-bit and 64-bit** versions.

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

.. literalinclude:: wheelnames.txt


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

If you unexpectedly run into problems installing the wheel for your system, please make sure you have updated your PIP to the current version.

