インストール#
要件#
以下のすべての例は、Pythonの仮想環境内で実行していると仮定しています。詳細については、https://docs.python.org/3/library/venv.html を参照してください。また、pipが最新であると仮定しています。
例えば:
Windows:
py -m venv pymupdf-venv .\pymupdf-venv\Scripts\activate python -m pip install --upgrade pip
Linux, MacOS:
python -m venv pymupdf-venv . pymupdf-venv/bin/activate python -m pip install --upgrade pip
インストール#
PyMuPDF should be installed using pip with:
pip install --upgrade pymupdf
この方法でインストールすると、対象のプラットフォームに対応するPythonのwheelファイルがある場合は、それを使用してインストールされます。
適切なwheelファイルが利用できない場合のインストール方法#
適切なPythonのwheelファイルが利用できない場合、pipは自動的にPythonのsdistからビルドします。
これにはC/C++の開発ツールがインストールされている必要があります：
Windowsの場合:
Visual Studio 2019をインストールしてください。標準の場所にインストールされていない場合は、環境変数
PYMUPDF_SETUP_DEVENVをdevenv.comバイナリの場所に設定してください他のバージョンのVisual Studio（例：Visual Studio 2022）がインストールされている場合、異なるコンパイラバージョンでMuPDFとPyMuPDFのコードがコンパイルされる可能性があるため、問題が発生することがあります。
自動的にMuPDFをダウンロードしてビルドします。
インストール後の問題#
On Windows, Python error:
ImportError: DLL load failed while importing _extra
これは、
MSVCP140.dllが見つからない場合に時折発生し、Microsoft Visual C++再頒布可能パッケージの一部のバージョン (2015 ～ 2017) のバグが原因であると思われます。https://msdn.com で
MSVCP140.dllを検索して、再インストールする方法の手順を見つけることをお勧めします。 たとえば、https://learn.microsoft.com/cpp/windows/latest-supported-vc-redist には、サポートされている最新バージョンへのパーマリンクがあります。詳細については、https://github.com/pymupdf/PyMuPDF/issues/2678 を参照してください。
Python error:
ModuleNotFoundError: No module named 'frontend'
This can happen if PyMuPDF's legacy name
fitzis used (for exampleimport fitzinstead ofimport pymupdf), and an unrelated Python package calledfitz(https://pypi.org/project/fitz/) is installed.The fitz package appears to be no longer maintained (the latest release is from 2017), but unfortunately it does not seem possible to remove it from pypi.org. It does not even work on its own, as well as breaking the use of PyMuPDF's legacy name.
There are a few ways to avoid this problem:
Use
import pymupdfinstead ofimport fitz, and update one's code to match.Or uninstall the
fitzpackage and reinstall PyMuPDF:pip uninstall fitz pip install --force-reinstall pymupdf
Or use
import pymupdf as fitz. However this has not been well tested.
With Jupyter labs on Apple Silicon (arm64), Python error:
ImportError: /opt/conda/lib/python3.11/site-packages/pymupdf/libmupdf.so.24.4: undefined symbol: fz_pclm_write_options_usage
This appears to be a problem in Jupyter labs; see: https://github.com/pymupdf/PyMuPDF/issues/3643#issuecomment-2210588778.
On Windows, Python error:
ImportError: dynamic module does not define module export function (PyInit__extra)
This was reported 2025-03-26 in https://github.com/pymupdf/PyMuPDF/issues/4405.
The fix appears to be to install the latest
VC_redist.x64.exe.
メモ#
Wheels are available for the following platforms:
Windows 32-bit Intel.
Windows 64-bit Intel.
Linux 64-bit Intel.
Linux 64-bit ARM.
MacOS 64-bit Intel.
MacOS 64-bit ARM.
Details:
We release a single wheel for each of the above platforms.
Each wheel uses the Python Stable ABI of the current oldest supported Python version (currently 3.10), and so works with all later Python versions, including new Python releases.
Wheels are tested on all Python versions currently marked as "Supported" on https://devguide.python.org/versions/, currently 3.9, 3.10, 3.11, 3.12, 3.13 and 3.14.
Chocolatey を使用してWindowsにインストールされたPythonには、ホイールが利用できません。代わりに、python.orgのウェブサイトからWindowsインストーラーを使用してPythonをインストールしてください。詳細は、以下を参照してください：http://www.python.org/downloads
Wheels are not available for Linux-aarch64 with Musl libc (For example Alpine Linux on aarch64), and building from source is known to fail.
必須の外部依存関係はありません。ただし、追加のコンポーネントをインストールした場合にのみ、一部のオプション機能が利用可能です：
Pillow は
Pixmap.pil_save()とPixmap.pil_tobytes()の実行に必要です。fontTools は
Document.subset_fonts()の実行に必要です。pymupdf-fonts は、テキスト出力の方法に使用するための素敵なフォントのコレクションです。
Tesseract-OCR for optical character recognition in images and document pages. Tesseract is separate software, not a Python package. To enable OCR functions in PyMuPDF, Tesseract must be installed and the
tessdatafolder name specified; see below.
注釈
これらの追加コンポーネントはいつでもインストールできます。PyMuPDFのインストール前または後に行うことができます。PyMuPDFは、これらのコンポーネントがインポート時または対応する機能が使用される際に検出します。
ローカルのPyMuPDFソースツリーからビルドしてインストールします#
初期設定：
上記に記載されているように、C/C++の開発ツールをインストールしてください。
上記に記載されているように、Pythonのvenvに入り、pipをアップデートしてください。
PyMuPDFのソースツリーを取得します：
PyMuPDFのGitリポジトリをクローンしてください:
git clone https://github.com/pymupdf/PyMuPDF.git
または、https://github.com/pymupdf/PyMuPDF/releases から
.zipまたは.tar.gz形式のソースリリースをダウンロードして展開してください。
PyMuPDFを2つの方法でビルドできます：
デフォルトのMuPDFバージョンでPyMuPDFをビルドしてインストール:
cd PyMuPDF && pip install .
これにより、特定のハードコードされたMuPDFソースリリースが自動的にダウンロードされ、PyMuPDFにビルドされます。
または、ローカルのMuPDFソースツリーを使用してPyMuPDFをビルドしてインストールします：
MuPDFのGitリポジトリをクローンします：
git clone --recursive https://git.ghostscript.com/mupdf.git
環境変数
PYMUPDF_SETUP_MUPDF_BUILDを使用して、ローカルな MuPDF ツリーの場所を指定して PyMuPDF をビルドします:cd PyMuPDF && PYMUPDF_SETUP_MUPDF_BUILD=../mupdf pip install .
同じPyMuPDFツリー内で異なるPythonバージョン用にビルドする方法：
PyMuPDF は、
pipを実行する Python のバージョンに対応してビルドされます。特定の Python バージョンで pip を実行するには、pipの代わりにpython -m pipを使用してください。したがって、Windows 上で異なるバージョンをビルドする場合、次のようにできます:
cd PyMuPDF && py -3.10 -m pip install .
または:
cd PyMuPDF && py -3.10-32 -m pip install .
テストの実行#
PyMuPDFのディレクトリが利用可能な場合、PyMuPDFの pytest テストスイートを実行できます。:
pip install pytest fontTools
pytest PyMuPDF/tests
非デフォルトのMuPDFを使用する際の注意事項#
環境変数 PYMUPDF_SETUP_MUPDF_BUILD を設定して非デフォルトのMuPDFビルドを使用すると、さまざまな問題が発生する可能性があるため、一般的にはサポートされていません。
もしMuPDFのメジャーバージョン番号がPyMuPDFがデフォルトで使用するものと異なる場合、PyMuPDFはビルドに失敗する可能性があります。なぜなら、MuPDFのAPIはメジャーバージョン間で変更されることがあるからです。
PyMuPDFのランタイム動作は、異なるマイナーリリース間でMuPDFのランタイム動作が変更されるため、変わる可能性があります。これは一部のPyMuPDFのテストにも影響を及ぼすことがあります。
MuPDFがPyMuPDFのカスタマイズされた設定ではなく、デフォルトの設定でビルドされた場合（たとえば、MuPDFがシステムにインストールされた場合）、
tests/test_textbox.py:test_textbox3()が失敗する可能性があります。この特定のテストをスキップするには、pytestコマンドラインに-k 'not test_textbox3'を追加してください。
Official PyMuPDF Linux wheels may not install on older Linux systems#
Releases of PyMuPDF are incompatible with older Linux systems.
For example as of 2025-09-03, pip install pymupdf does not work on some AWS
Lambda systems - see https://github.com/pymupdf/PyMuPDF/discussions/4631.
This is because official PyMuPDF Linux wheels are built with a version of glibc determined by the current Python manylinux environment. These wheels are incompatible with Linux systems that have an older glibc.
The official Python manylinux environment is updated periodically to use newer glibc versions, so new releases of PyMuPDF become increasingly incompatible with older Linux systems.
There is nothing that can be done about this, other than updating older Linux systems, or building PyMuPDF locally from source.
For more details, please see: Python Packaging Authority.
パッケージング#
Linux ディストリビューション向けのパッケージング を参照してください。
Pyodideとの使用#
Pyodide を参照してください。
統合OCRサポートの有効化#
もしこの機能を使用しない場合は、このステップをスキップしてください。それ以外の場合は、ホイールからのインストールとソースからのインストールの両方 に必要です。
PyMuPDFにはすでにOCR機能をサポートするためのロジックが含まれていますが、追加でTesseractの言語サポートデータが必要です。そのため、Tesseract-OCRのインストールが依然として必要です。
If not specified explicitly, PyMuPDF will attempt to find the installed Tesseract's tessdata, but this should probably not be relied upon.
Otherwise PyMuPDF requires that Tesseract's language support folder is
specified explicitly either in PyMuPDF OCR functions' tessdata arguments or
os.environ["TESSDATA_PREFIX"].
OCR機能を正常に動作させるために、以下のチェックリストを完了してください：
Tesseractの言語サポートフォルダを見つけてください。通常、以下の場所にあります：
Windows:
C:/Program Files/Tesseract-OCR/tessdataUnixシステム:
/usr/share/tesseract-ocr/4.00/tessdata
Specify the language support folder when calling PyMuPDF OCR functions:
Set the
tessdataargument.Or set
os.environ["TESSDATA_PREFIX"]from within Python.Or set environment variable
TESSDATA_PREFIXbefore running Python, for example:Windows:
setx TESSDATA_PREFIX "C:/Program Files/Tesseract-OCR/tessdata"Unixシステム:
declare -x TESSDATA_PREFIX=/usr/share/tesseract-ocr/4.00/tessdata
注釈
Find out more on the official documentation for installing Tesseract website.