Skip to content

DOC: document the issues with overlaying new mpl on old mpl #29673

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

Merged
merged 4 commits into from
May 2, 2025
+19 −0
Merged

DOC: document the issues with overlaying new mpl on old mpl #29673

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
4f87488
DOC: document the issues with overlaying new mpl on old mpl
tacaswell Feb 24, 2025
96c5403
DOC: add note about how to avoid overlaying multiple versions of mpl
tacaswell Feb 24, 2025
fc00227
Update doc/api/prev_api_changes/api_changes_3.8.0/behaviour.rst
tacaswell Feb 24, 2025
3f1b7f7
Spelling/grammar
ksunden May 2, 2025
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
19 changes: 19 additions & 0 deletions doc/api/prev_api_changes/api_changes_3.8.0/behaviour.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -171,3 +171,22 @@ saved.

Previously, *mincnt* was inclusive with no *C* provided but exclusive when *C* is provided.
It is now inclusive of *mincnt* in both cases.


``matplotlib.mpl_toolkits`` is now an implicit namespace package
----------------------------------------------------------------

Following the deprecation of ``pkg_resources.declare_namespace`` in ``setuptools`` 67.3.0,
``matplotlib.mpl_toolkits`` is now implemented as an implicit namespace, following
`PEP 420 <https://peps.python.org/pep-0420/>`_.

As a consequence using ``pip`` to install a version of Matplotlib >= 3.8 on top
of a version of Matplotlib < 3.8 (e.g. via ``pip install --local`` or
``python -m venv --system-site-packages ...``) will fail because the old
``matplotlib.mpl_toolkits`` files will be found whereas the newer files will be
found for all other modules. This will result in errors due to the version
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is there anything we can do about this? eg somehow clean out the old files on pip install, I guess by overwriting them with empty files?

Or barring that, it would be helpful if we suggested to users what they should do about this. I'm not even sure pip uninstall matplotlib will clean the mpl_toolkits files out.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The issue is the "overlaying". If the old version of Matplotlib is in the venv (and hence the users has write) then pip takes care of itself, but if you are exposed to a read-only set of files then there is nothing we can do.

Even if there was something to do, it would be pip's job not ours.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is still a bit mysterious, and I don't think I am in a low percentile of our user's sophistication in installing python packages, so can we be more clear? Is this primarily happening when the operating system has packaged matplotlib as part of the distribution (or apt-install etc), and then the user's pip-install doesn't replace mpl-toolkits in the distribution's version of Matplotlib? If that is the most common case, can we just say something like that, while leaving open the possibility that the installation got crossed other ways.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this primarily happening when the operating system has packaged matplotlib as part of the distribution (or apt-install etc), and then the user's pip-install doesn't replace mpl-toolkits in the distribution's version of Matplotlib?

Yes, that is the common (and likely only?) case.

mismatch.

To avoid this issue you need to avoid having multiple versions of Matplotlib
in different entries of ``sys.path``. Either uninstall Matplotlib
at the system level or use a more isolated virtual environment.