Installation
=============

PyMuPDF can be installed from Python wheels for Windows (32bit and 64bit), Linux (64bit, Intel and ARM) and Mac OSX (64bit, Intel), Python versions 3.6 and up::

  python -m pip install --upgrade pip
  python -m pip install --upgrade pymupdf

There are no **mandatory** external dependencies. However, some optional feature are available only if additional components are installed:

* `Pillow <https://pypi.org/project/Pillow/>`_ is required for :meth:`Pixmap.pil_save` and :meth:`Pixmap.pil_tobytes`.
* `fontTools <https://pypi.org/project/fonttools/>`_ is required for :meth:`Document.subset_fonts`.
* `pymupdf-fonts <https://pypi.org/project/pymupdf-fonts/>`_ is a collection of nice fonts to be used for text output methods.
* `Tesseract-OCR <https://github.com/tesseract-ocr/tesseract>`_ for optical character recognition in images and document pages. Tesseract is separate software, not a Python package. To enable OCR functions in PyMuPDF, the system environment variable ``"TESSDATA_PREFIX"`` must be defined and contain the ``tessdata`` folder name of the Tesseract installation location.

.. note:: You can install these additional components at any time -- before or after installing PyMuPDF. PyMuPDF will detect their presence during import or when the respective functions are being used.

PyMuPDF does not support Python versions prior to 3.6. Some older wheels can be found `here <https://github.com/pymupdf/PyMuPDF-Optional-Material/tree/master/wheels-upto-Py3.5>`_.

To **install from sources**, follow these steps:


Step 1: Install MuPDF
~~~~~~~~~~~~~~~~~~~~~~~~~
For open source GNU AGPL licenses download from `here <https://mupdf.com/downloads/archive>`_.

If you are a commercial customer, please contact `Artifex <https://artifex.com/contact/>`_.

Install following the instructions for your platform.


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

Adjust the setup.py script when necessary. Especially make sure that ``include_dirs`` and ``library_dirs`` point to the folders of your MuPDF installation. The easiest way to do this is setting the environment variable ``"PYMUPDF_DIRS"`` to the name of a JSON file, that contains a dictionary with these two keys having a list of folder names as values::

    {
      "include_dirs": ["folder1", "folder2", "folder3", ...],
      "library_dirs": ["folder1", "folder2", "folder3", ...],
    }

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

Step 3: Enable Tesseract-OCR Support
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
With the above steps, PyMuPDF contains all logic to support OCR functions. Tesseract is however not a Python package, but separate software that must be installed on the system.

To use it, (Py-) MuPDF needs to be told the location of Tesseract's language support folder. This currently happens via storing this folder name in the environment variable ``"TESSDATA_PREFIX"``.

In Windows, a typical way to define this name is::

    set TESSDATA_PREFIX=C:\Program Files\Tesseract-OCR\tessdata

On Unix systems one might execute::

    export TESSDATA_PREFIX=/usr/share/tesseract-ocr/4.00/tessdata
