インストール#

要件#

以下のすべての例は、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をインストールするには、次のようにpipを使用してください:

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のコードがコンパイルされる可能性があるため、問題が発生することがあります。

PyMuPDF-1.20.0 現在、必要なMuPDFのソースコードがsdistに含まれており、自動的にPyMuPDFに組み込まれています。

インストール後の問題#

  • Windowsの場合: ImportError: DLL load failed while importing _fitz.

    これは、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 を参照してください。

メモ#

ホイールは、Windows向けには（32ビットIntel、64ビットIntel）、Linux向けには（64ビットIntel、64ビットARM）、およびMac OSX向けには（64ビットIntel、64ビットARM）提供されています。 Pythonのバージョンは、「https://devguide.python.org/versions/」で「サポートされている」とマークされています。

Chocolatey を使用してWindowsにインストールされたPythonには、ホイールが利用できません。代わりに、python.orgのウェブサイトからWindowsインストーラーを使用してPythonをインストールしてください。詳細は、以下を参照してください：http://www.python.org/downloads

PyMuPDFはPythonバージョン3.8以前をサポートしていません。古いバージョンのホイールは、この リポジトリや PyPI でも見つけることができます

必須の外部依存関係はありません。ただし、追加のコンポーネントをインストールした場合にのみ、一部のオプション機能が利用可能です：

  • Pillow は Pixmap.pil_save() と Pixmap.pil_tobytes() の実行に必要です。

  • fontTools は Document.subset_fonts() の実行に必要です。

  • pymupdf-fonts は、テキスト出力の方法に使用するための素敵なフォントのコレクションです。

  • Tesseract-OCR は、画像やドキュメントページの光学文字認識（OCR）のためのソフトウェアです。TesseractはPythonのパッケージではなく、独立したソフトウェアです。PyMuPDFでOCR機能を有効にするには、Tesseractソフトウェアをインストールし、システム環境変数の "TESSDATA_PREFIX" を定義して、Tesseractのインストール場所にある tessdata フォルダの名前を含める必要があります。以下を参照してください。

注釈

これらの追加コンポーネントはいつでもインストールできます。PyMuPDFのインストール前または後に行うことができます。PyMuPDFは、これらのコンポーネントがインポート時または対応する機能が使用される際に検出します。

ローカルの PyMuPDF チェックアウトとオプションのローカル MuPDF チェックアウトからビルドしてインストールします。#

  • 上記に記載されているように、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をビルドしてインストールしてください:

    cd PyMuPDF && pip install .

    これにより、特定のハードコードされたMuPDFソースリリースが自動的にダウンロードされ、PyMuPDFにビルドされます。

ローカルのMuPDFソースツリーを使用してPyMuPDFをビルドおよびインストールする場合は、次の手順に従ってください：

  • MuPDFのGitリポジトリをクローンします：

    git clone --recursive https://ghostscript.com:/home/git/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.9 -m pip install .

    または:

    cd PyMuPDF && py -3.10-32 -m pip install .

注釈

PyMuPDFを使用するPythonスクリプトを実行する際は、現在のディレクトリが PyMuPDF/ ディレクトリでないことを確認してください。

そうでない場合、Pythonは混乱する可能性があります。Pythonはローカルの fitz/ ディレクトリから fitz をインポートしようとしますが、それはソースファイルのみを含んでいるため、失敗します。

テストの実行#

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' を追加してください。

パッケージング#

Linux ディストリビューション向けのパッケージング を参照してください。

Pyodideとの使用#

Pyodide を参照してください。

統合OCRサポートの有効化#

もしこの機能を使用しない場合は、このステップをスキップしてください。それ以外の場合は、ホイールからのインストールとソースからのインストールの両方 に必要です。

PyMuPDFにはすでにOCR機能をサポートするためのロジックが含まれていますが、追加でTesseractの言語サポートデータが必要です。そのため、Tesseract-OCRのインストールが依然として必要です。

言語サポートフォルダの場所は、"TESSDATA_PREFIX" という環境変数に保存するか、適用される関数のパラメータとして指定する必要があります。

OCR機能を正常に動作させるために、以下のチェックリストを完了してください：

  1. Tesseractの言語サポートフォルダを見つけてください。通常、以下の場所にあります：

    • Windows: C:/Program Files/Tesseract-OCR/tessdata

    • Unixシステム: /usr/share/tesseract-ocr/4.00/tessdata

  2. 環境変数 TESSDATA_PREFIX を設定してください：

    • Windows: setx TESSDATA_PREFIX "C:/Program Files/Tesseract-OCR/tessdata"

    • Unixシステム: declare -x TESSDATA_PREFIX=/usr/share/tesseract-ocr/4.00/tessdata

注釈

Windowsシステムでは、これはPythonの外部で行われる必要があります。スクリプトを実行する前に行ってください。os.environ を操作するだけではうまく動作しません！

This software is provided AS-IS with no warranty, either express or implied. This software is distributed under license and may not be copied, modified or distributed except as expressly authorized under the terms of that license. Refer to licensing information at artifex.com or contact Artifex Software Inc., 39 Mesa Street, Suite 108A, San Francisco CA 94129, United States for further information.

このドキュメントは 1.24.3 までのすべてのバージョンを対象としています。

Discord logo