Merge pull request matplotlib#29673 from tacaswell/doc/namespace_incompatibility

ksunden · web-flow · commit cfe41d48b741 · 2025-05-02T13:57:51.000-05:00
DOC: document the issues with overlaying new mpl on old mpl
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
@@ -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
+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.
