PyMuPDF: "The fitz API is deprecated" and "No module named 'fitz'"

The messages

warning: The `fitz` API is deprecated and will be removed in future. Use `import pymupdf` instead.

ModuleNotFoundError: No module named 'fitz'

Background: one library, two names

PyMuPDF is installed as pymupdf but was historically imported as fitz, after MuPDF’s original graphics engine. Since version 1.24.3 the recommended import is pymupdf. With PyMuPDF 1.28.2, import fitz still works but prints the deprecation warning above. We checked that fitz.open and pymupdf.open are the same function.

Fix the deprecation warning

Change the import. Nothing else needs to change:

# Before
import fitz
doc = fitz.open("input.pdf")

# After
import pymupdf
doc = pymupdf.open("input.pdf")

For a large codebase you can switch gradually with an alias:

import pymupdf as fitz   # no warning; replace fitz.* calls over time

Fix “No module named ‘fitz’” or “No module named ‘pymupdf’”

PyMuPDF isn’t installed in the Python environment you’re running. Install the right package:

pip install pymupdf

Then make sure you’re using the same interpreter you installed into:

python -m pip install pymupdf   # installs for exactly this python
python -c "import pymupdf; print(pymupdf.__doc__)"

In Jupyter, run %pip install pymupdf in a cell so it installs into the notebook’s kernel.

Don’t pip install fitz

It’s tempting, because the error mentions fitz, but fitz on PyPI is not PyMuPDF. For years it was an unrelated package that broke imports; today the name is held by the PyMuPDF maintainers as an empty placeholder (version 0.0.0). Either way it won’t give you PyMuPDF.

If you installed it, clean up:

pip uninstall -y fitz
pip install --force-reinstall pymupdf

Also check for a local file named fitz.py or pymupdf.py

A file in your project with the same name as the library shadows it, causing confusing errors like module 'pymupdf' has no attribute 'open'. Rename your file (and delete any __pycache__ folder next to it).

Next

• PyMuPDF tutorial
• Python PDF libraries compared