Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs/: improve description of conflict with fitz package. #3674

Merged
merged 1 commit into from
Jul 10, 2024
Merged

docs/: improve description of conflict with fitz package. #3674

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 36 additions & 3 deletions docs/installation.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,10 +60,14 @@ source using a Python sdist.
The build will automatically download and build MuPDF.


.. _problems-after-installation:

Problems after installation
---------------------------------------------------------

* On Windows `ImportError: DLL load failed while importing _fitz`.
* On Windows, Python error::

ImportError: DLL load failed while importing _fitz

This has been occasionally seen if `MSVCP140.dll` is missing, and appears
to be caused by a bug in some versions (2015-2017) of `Microsoft Visual C++
Expand All @@ -77,8 +81,37 @@ Problems after installation
See https://github.com/pymupdf/PyMuPDF/issues/2678 for more details.

*
Problems have been reported when using PyMuPDF with Jupyter labs on Apple
Silicon (arm64); see https://github.com/pymupdf/PyMuPDF/issues/3643.
Python error::

ModuleNotFoundError: No module named 'frontend'

This can happen if PyMuPDF's legacy name `fitz` is used (for example `import
fitz` instead of `import pymupdf`), and an unrelated Python package called
`fitz` (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 pymupdf` instead of `import fitz`, and update one's code to
match.

* Or uninstall the `fitz` package 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

See https://github.com/pymupdf/PyMuPDF/issues/3643#issuecomment-2210588778.


Notes
Expand Down
7 changes: 6 additions & 1 deletion docs/intro.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,12 @@ The original rendering library for MuPDF was called *Libart*.

*"After Artifex Software acquired the MuPDF project, the development focus shifted on writing a new modern graphics library called "Fitz". Fitz was originally intended as an R&D project to replace the aging Ghostscript graphics library, but has instead become the rendering engine powering MuPDF."* (Quoted from `Wikipedia <https://en.wikipedia.org/wiki/MuPDF>`_).

`import fitz` is still supported for backwards compatibility, but this usage **cannot coexist** with packages named "fitz" in the same Python environment.
`import fitz` is still supported for backwards compatibility.

.. note::

Use of legacy name `fitz` can fail if defunct package pypi.org `fitz` is installed; see :ref:`problems-after-installation`.


License and Copyright
----------------------
Expand Down
3 changes: 1 addition & 2 deletions docs/tutorial.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,10 +35,9 @@ The original rendering library for MuPDF was called *Libart*.

*"After Artifex Software acquired the MuPDF project, the development focus shifted on writing a new modern graphics library called "Fitz". Fitz was originally intended as an R&D project to replace the aging Ghostscript graphics library, but has instead become the rendering engine powering MuPDF."* (Quoted from `Wikipedia <https://en.wikipedia.org/wiki/MuPDF>`_).


.. note::

Importing |PyMuPDF| as `fitz` still works however |PyMuPDF| **cannot coexist** with other packages named "fitz" in the same Python environment.
Use of legacy name `fitz` can fail if defunct pypi.org package `fitz` is installed; see :ref:`problems-after-installation`.


.. _Tutorial_Opening_a_Document:
Expand Down
Loading