matplotlib · ksunden · Jan 17, 2024 · Dec 20, 2023
diff --git a/.github/workflows/cygwin.yml b/.github/workflows/cygwin.yml
@@ -242,7 +242,7 @@ jobs:
         shell: bash.exe -eo pipefail -o igncr "{0}"
         id: cygwin-run-pytest
         run: |
-          xvfb-run python -mpytest -raR -n auto \
+          xvfb-run pytest -raR -n auto \
             --maxfail=50 --timeout=300 --durations=25 \
             --cov-report=xml --cov=lib --log-level=DEBUG --color=yes
 

diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
@@ -316,7 +316,7 @@ jobs:
 
       - name: Run pytest
         run: |
-          python -mpytest -raR -n auto \
+          pytest -raR -n auto \
             --maxfail=50 --timeout=300 --durations=25 \
             --cov-report=xml --cov=lib --log-level=DEBUG --color=yes
 

diff --git a/azure-pipelines.yml b/azure-pipelines.yml
@@ -225,7 +225,7 @@ stages:
             fi
             echo "##vso[task.setvariable variable=VS_COVERAGE_TOOL]$TOOL"
           fi
-          PYTHONFAULTHANDLER=1 python -m pytest -raR -n 2 \
+          PYTHONFAULTHANDLER=1 pytest -raR -n 2 \
               --maxfail=50 --timeout=300 --durations=25 \
               --junitxml=junit/test-results.xml --cov-report=xml --cov=lib ||
             [[ "$PYTHON_VERSION" = 'Pre' ]]

diff --git a/doc/api/prev_api_changes/api_changes_3.5.0/deprecations.rst b/doc/api/prev_api_changes/api_changes_3.5.0/deprecations.rst
@@ -353,7 +353,7 @@ is thus deprecated as well.
 To test an installed copy, be sure to specify both ``matplotlib`` and
 ``mpl_toolkits`` with ``--pyargs``::
 
-    python -m pytest --pyargs matplotlib.tests mpl_toolkits.tests
+    pytest --pyargs matplotlib.tests mpl_toolkits.tests
 
 See :ref:`testing` for more details.
 

diff --git a/doc/api/prev_api_changes/api_changes_3.7.0/removals.rst b/doc/api/prev_api_changes/api_changes_3.7.0/removals.rst
@@ -185,7 +185,7 @@ is thus removed as well.
 To test an installed copy, be sure to specify both ``matplotlib`` and
 ``mpl_toolkits`` with ``--pyargs``::
 
-    python -m pytest --pyargs matplotlib.tests mpl_toolkits.tests
+    pytest --pyargs matplotlib.tests mpl_toolkits.tests
 
 See :ref:`testing` for more details.
 

diff --git a/doc/devel/testing.rst b/doc/devel/testing.rst
@@ -37,11 +37,11 @@ Running the tests
 
 In the root directory of your development repository run::
 
-   python -m pytest
+   pytest
 
 
-pytest can be configured via a lot of `command-line parameters`_. Some
-particularly useful ones are:
+``pytest`` can be configured via many :external+pytest:doc:`command-line parameters
+<how-to/usage>`. Some particularly useful ones are:
 
 =============================  ===========
 ``-v`` or ``--verbose``        Be more verbose
@@ -50,14 +50,32 @@ particularly useful ones are:
 ``--capture=no`` or ``-s``     Do not capture stdout
 =============================  ===========
 
-To run a single test from the command line, you can provide a file path,
-optionally followed by the function separated by two colons, e.g., (tests do
-not need to be installed, but Matplotlib should be)::
+To run a single test from the command line, you can provide a file path, optionally
+followed by the function separated by two colons, e.g., (tests do not need to be
+installed, but Matplotlib should be)::
 
   pytest lib/matplotlib/tests/test_simplification.py::test_clipping
 
+If you want to use ``pytest`` as a module (via ``python -m pytest``), then you will need
+to avoid clashes between ``pytest``'s import mode and Python's search path:
 
-.. _command-line parameters: http://doc.pytest.org/en/latest/usage.html
+- On more recent Python, you may :external+python:std:option:`disable "unsafe import
+  paths" <-P>` (i.e., stop adding the current directory to the import path) with the
+  ``-P`` argument::
+
+      python -P -m pytest
+
+- On older Python, you may enable :external+python:std:option:`isolated mode <-I>`
+  (which stops adding the current directory to the import path, but has other
+  repercussions)::
+
+      python -I -m pytest
+
+- On any Python, set ``pytest``'s :external+pytest:doc:`import mode
+  <explanation/pythonpath>` to the older ``prepend`` mode (but note that this will break
+  ``pytest``'s assert rewriting)::
+
+      python -m pytest --import-mode prepend
 
 Viewing image test output
 ^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -302,11 +320,12 @@ is necessary for testing ``mpl_toolkits``.
 
 Run the tests
 ^^^^^^^^^^^^^
-To run the all the tests on your installed version of Matplotlib::
 
-    python -m pytest --pyargs matplotlib.tests
+To run all the tests on your installed version of Matplotlib::
+
+    pytest --pyargs matplotlib.tests
 
 The test discovery scope can be narrowed to single test modules or even single
 functions::
 
-    python -m pytest --pyargs matplotlib.tests.test_simplification.py::test_clipping
+    pytest --pyargs matplotlib.tests.test_simplification.py::test_clipping
diff --git a/pyproject.toml b/pyproject.toml
@@ -298,3 +298,6 @@ ignore_messages = [
 # `lib/matplotlib/testing/conftest.py`.
 minversion = "7.0"
 testpaths = ["lib"]
+addopts = [
+    "--import-mode=importlib",
+]