May 2, 2025 · Feb 24, 2025 · Feb 24, 2025 · Feb 24, 2025 · May 2, 2025 · Feb 24, 2025
diff --git a/doc/api/prev_api_changes/api_changes_3.8.0/behaviour.rst b/doc/api/prev_api_changes/api_changes_3.8.0/behaviour.rst

 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
 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.
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 jklymakFeb 24, 2025 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 whatthey should do about this. I'm not even sure`pip uninstall matplotlib` will clean the mpl_toolkits files out. Copy link MemberAuthor tacaswellFeb 24, 2025 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 jklymakFeb 24, 2025 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 QuLogicFeb 25, 2025 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. jklymak reacted with thumbs up emoji
		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.