Dependency version policy#

For the purpose of this document, 'minor version' is in the sense of SemVer(major, minor, patch) or 'meso version' in the sense ofEffVer (macro, meso, micro). It includes bothmajor/macro and minor/meso releases. For projects that use date-basedversioning, every release is a 'minor version'.

Matplotlib followsNEP 29.

Python and NumPy#

Matplotlib supports:

  • All minor versions of Python released 42 months prior to theproject, and at minimum the two latest minor versions.

  • All minor versions ofnumpy released in the 24 months priorto the project, and at minimum the last three minor versions.

Inpyproject.toml, therequires-python variable should be set tothe minimum supported version of Python. All supported minorversions of Python should be in the test matrix and have binaryartifacts built for the release.

Minimum Python and NumPy version support should be adjusted upwardon every major and minor release, but never on a patch release.

See also theList of dependency versions.

Python dependencies#

For Python dependencies we should support at least:

with compiled extensions

minor versions initially released in the 24 months prior to our plannedrelease date or the oldest that support our minimum Python + NumPy

without compiled extensions

minor versions initially released in the 12 months prior to our plannedrelease date or the oldest that supports our minimum Python.

We will only bump these dependencies as we need new features or the oldversions no longer support our minimum NumPy or Python.

We will work around bugs in our dependencies when practical.

IPython and Matplotlib do not formally depend on each other, however there ispractical coupling for the integration of Matplotlib's UI into IPython andIPykernel. We will ensure this integration works with at least minor or majorversions of IPython and IPykernel released in the 24 months prior to ourplanned release date. Matplotlib may or may not work with older versions andwe will not warn if used with IPython or IPykernel outside of this window.

Test and documentation dependencies#

As these packages are only needed for testing or building the docs andnot needed by end-users, we can be more aggressive about droppingsupport for old versions. However, we need to be careful to notover-run what down-stream packagers support (as most of the run thetests and build the documentation as part of the packaging process).

We will support at least minor versions of the development dependenciesreleased in the 12 months prior to our planned release. Specific versions thatare known to be buggy may be excluded from support using the finest-grainedfiltering that is practical.

We will only bump these as needed or versions no longer support ourminimum Python and NumPy.

System and C-dependencies#

For system or C-dependencies (FreeType, GUI frameworks, LaTeX,Ghostscript, FFmpeg) support as old as practical. These can be difficult toinstall for end-users and we want to be usable on as many systems aspossible. We will bump these on a case-by-case basis.

In the case of GUI frameworks for which we rely on Python bindings beingavailable, we will also drop support for bindings so old that they don'tsupport any Python version that we support.

Security issues in dependencies#

Generally, we do not adjust the supported versions of dependencies based onsecurity vulnerabilities. We are a library not an applicationand the version constraints on our dependencies indicate what will work (notwhat is wise to use). Users and packagers can install newer versions of thedependencies at their discretion and evaluation of risk and impact. Incontrast, if we were to adjust our minimum supported version it is very hardfor a user to override our judgment.

If Matplotlib aids in exploiting the underlying vulnerability we should treatthat as a critical bug in Matplotlib.

List of dependency versions#

The following list shows the minimal versions of Python and NumPy dependenciesfor different versions of Matplotlib. Follow the links for the fullspecification of the dependencies.

Matplotlib

Python

NumPy

3.11

3.11

1.25.0

3.10

3.10

1.23.0

3.9

3.9

1.23.0

3.8

3.9

1.21.0

3.7

3.8

1.20.0

3.6

3.8

1.19.0

3.5

3.7

1.17.0

3.4

3.7

1.16.0

3.3

3.6

1.15.0

3.2

3.6

1.11.0

3.1

3.6

1.11.0

3.0

3.5

1.10.0

2.2

2.7, 3.4

1.7.1

2.1

2.7, 3.4

1.7.1

2.0

2.7, 3.4

1.7.1

1.5

2.7, 3.4

1.6

1.4

2.6, 3.3

1.6

1.3

2.6, 3.3

1.5

1.2

2.6, 3.1

1.4

1.1

2.4

1.1

1.0

2.4

1.1

Updating Python and NumPy versions#

To update the minimum versions of Python we need to update:

  • pyproject.toml (classifiers, requires-python,[tool.ruff] target-version)

  • environment.yml

  • doc/install/dependencies.rst

  • doc/devel/min_dep_policy.rst (this file)

  • CI configuration files (circle, GHA, azure)

  • tox.ini

To update the minimum NumPy we need to update:

  • pyproject.toml

  • environment.yml

  • doc/install/dependencies.rst

  • doc/devel/min_dep_policy.rst (this file)

  • requirements/testing/minver.txt

  • lib/matplotlib/__init__.py (matplotlib._check_versions())

The work to leverage new features or remove workarounds for no-longer supportedversions should be done in a follow-on PRs to keep the version bump PRs wellscoped.

In both cases add an api_changes/development with the following template:

Increase to minimum supported versions of dependencies~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~For Matplotlib 3.ZZ, the:ref:`minimum supported versions <dependencies>` arebeing bumped:+------------+-----------------+----------------+| Dependency |  min in mpl3.N  | min in mpl3.M  |+============+=================+================+|   Python   |       3.XX      |       3.AA     ||   NumPy    |       1.YY      |       1.BB     |+------------+-----------------+----------------+This is consistent with our:ref:`min_deps_policy` and `SPEC0<https://scientific-python.org/specs/spec-0000/>`__