How to Install PyMuPDF in CI Without Build Failures

PyMuPDF ships wheels with the MuPDF C library bundled, so installs are fast - until a too-new Python or musl forces a heavy MuPDF source build, or you import the wrong name.

PyMuPDF wraps the MuPDF C library and ships manylinux wheels with MuPDF bundled, so a correct install just downloads a wheel and needs no system libraries. CI breaks when a brand-new Python or Alpine/musl has no wheel (forcing a long MuPDF compile), or when code imports the legacy fitz name unexpectedly.

Why it fails in CI

With no matching wheel, pip compiles MuPDF from source - a long C/C++ build needing a toolchain that slim and Alpine images lack. The other common confusion is the import name: PyMuPDF historically imports as fitz (newer versions also expose pymupdf).

• Could not find a version that satisfies the requirement PyMuPDF on a new Python/musl.
• Failed building wheel for PyMuPDF - compiling MuPDF from source.
• ModuleNotFoundError: No module named 'fitz' - install/import-name confusion.

Install it reliably

Keep the wheel: glibc base, a supported Python, force-binary. MuPDF is bundled, so no system library is needed. Import pymupdf (or fitz) per your installed version.

# Force the prebuilt wheel - MuPDF is bundled
pip install --only-binary=:all: PyMuPDF

# import name (newer versions support both):
#   import pymupdf      # or:  import fitz

Cache & speed

Cache ~/.cache/pip so the wheel is reused. Avoiding the MuPDF source build is the dominant speedup.

- uses: actions/cache@v4
  with:
    path: ~/.cache/pip
    key: pip-pymupdf-${{ hashFiles('requirements*.txt') }}

Common errors

Key takeaways

• PyMuPDF wheels bundle MuPDF - never compile it in CI.
• Glibc base + a supported Python keeps you on the wheel.
• Import pymupdf or fitz depending on your installed version.

Related guides