From 2c64e81d38fb7ba49d4196996642ca92d762e418 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 22 Oct 2026 14:16:36 +0000 Subject: [PATCH 1/3] docs: show venv/pip, uv and virtualenv installs The getting-started page told users to run a bare `pip install -U pytest`, which fails with `externally-managed-environment` (PEP 668) on many current systems. Install into a virtual environment instead, with tabs for venv + pip, uv and virtualenv, and update the good-practices section to use a `dev` dependency group that both pip (>= 25.1) and uv understand. Closes #15242 Co-Authored-By: Claude Opus 5.5 (1M context) --- changelog/15242.doc.rst | 1 + doc/en/explanation/goodpractices.rst | 55 ++++++++++++++++++++++++---- doc/en/getting-started.rst | 50 +++++++++++++++++++++++-- 3 files changed, 95 insertions(+), 11 deletions(-) create mode 100644 changelog/15242.doc.rst diff --git a/changelog/15242.doc.rst b/changelog/15242.doc.rst new file mode 100644 index 00000000000..b3e4ff49a41 --- /dev/null +++ b/changelog/15242.doc.rst @@ -0,0 +1 @@ +The :ref:`installation instructions ` and :ref:`install-package-with-pip` now show how to install pytest into a virtual environment with venv and pip, uv or virtualenv, and explain the ``externally-managed-environment`` error. diff --git a/doc/en/explanation/goodpractices.rst b/doc/en/explanation/goodpractices.rst index 8314fe447f7..4594e3a7d7b 100644 --- a/doc/en/explanation/goodpractices.rst +++ b/doc/en/explanation/goodpractices.rst @@ -4,13 +4,16 @@ Good Integration Practices ================================================= -Install package with pip +.. _`install-package-with-pip`: + +Install package in a virtual environment ------------------------------------------------- -For development, we recommend you use :mod:`venv` for virtual environments and -:doc:`pip:index` for installing your application and any dependencies, -as well as the ``pytest`` package itself. -This ensures your code and dependencies are isolated from your system Python installation. +For development, we recommend that you install your application, its dependencies +and the ``pytest`` package itself into a virtual environment. +This ensures your code and dependencies are isolated from your system Python installation, +and avoids the ``externally-managed-environment`` error (:pep:`668`) +that many operating systems raise for installs into their own Python. Create a ``pyproject.toml`` file in the root of your repository as described in :doc:`packaging:tutorials/packaging-projects`. @@ -26,13 +29,49 @@ The first few lines should look like this: name = "PACKAGENAME" version = "PACKAGEVERSION" + [dependency-groups] + dev = ["pytest"] + where ``PACKAGENAME`` and ``PACKAGEVERSION`` are the name and version of your package respectively. +The ``dev`` :doc:`dependency group ` lists the +tools you need for development, such as ``pytest``. -You can then install your package in "editable" mode by running from the same directory: +You can then create a virtual environment and install your package in "editable" mode, +together with the ``dev`` group, by running from the same directory: -.. code-block:: bash +.. tab:: venv + pip + + Uses :mod:`venv` and :doc:`pip ` + (``pip install --group`` needs pip 25.1 or newer): + + .. code-block:: bash + + python3 -m venv .venv + source .venv/bin/activate # on Windows: .venv\Scripts\activate + pip install -e . --group dev + pytest + +.. tab:: uv + + `uv `__ creates ``.venv``, installs your + package in editable mode and installs the ``dev`` group by default: + + .. code-block:: bash + + uv sync + uv run pytest + +.. tab:: virtualenv + + Same as with :mod:`venv`, but the environment is created by + :doc:`virtualenv `: + + .. code-block:: bash - pip install -e . + virtualenv .venv + source .venv/bin/activate # on Windows: .venv\Scripts\activate + pip install -e . --group dev + pytest which lets you change your source code (both tests and application) and rerun tests at will. diff --git a/doc/en/getting-started.rst b/doc/en/getting-started.rst index f8deae77e3e..02b4741dc47 100644 --- a/doc/en/getting-started.rst +++ b/doc/en/getting-started.rst @@ -9,11 +9,52 @@ Get Started Install ``pytest`` ---------------------------------------- -1. Run the following command in your command line: +Install ``pytest`` into a virtual environment, not into the Python installation +of your operating system. +Many systems, such as recent Debian, Ubuntu and Fedora releases, refuse a plain +``pip install`` outside a virtual environment with +``error: externally-managed-environment`` (see :pep:`668`). +Do not work around this with ``--break-system-packages``; +create a virtual environment instead. -.. code-block:: bash +1. Create a virtual environment and install ``pytest`` into it, + using the tool of your choice: + +.. tab:: venv + pip + + :mod:`venv` and :doc:`pip ` ship with Python. + Some Linux distributions package them separately + (for example ``python3-venv`` on Debian and Ubuntu). + + .. code-block:: bash + + python3 -m venv .venv + source .venv/bin/activate # on Windows: .venv\Scripts\activate + pip install -U pytest + +.. tab:: uv + + `uv `__ creates and manages the virtual + environment of your project for you. + In a directory with a ``pyproject.toml`` (``uv init`` creates one): - pip install -U pytest + .. code-block:: bash + + uv add --dev pytest + + Prefix the ``pytest`` commands on this page with ``uv run``, + for example ``uv run pytest``, to run them inside the project environment. + +.. tab:: virtualenv + + :doc:`virtualenv ` is a faster, more configurable + alternative to :mod:`venv`: + + .. code-block:: bash + + virtualenv .venv + source .venv/bin/activate # on Windows: .venv\Scripts\activate + pip install -U pytest 2. Check that you installed the correct version: @@ -22,6 +63,9 @@ Install ``pytest`` $ pytest --version pytest 9.1.1 +See :ref:`install-package-with-pip` for how to install the project you are +testing into the same environment. + .. _`simpletest`: Create your first test From fdb318c9070ed3d407d14d8f835e49669bffc0cc Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 25 Oct 2026 14:18:06 +0000 Subject: [PATCH 2/3] docs: move externally-managed-environment note to good practices Keeps the getting-started page short, as suggested in review. Co-Authored-By: Claude Opus 5.5 (1M context) --- doc/en/explanation/goodpractices.rst | 13 ++++++++++--- doc/en/getting-started.rst | 7 +------ 2 files changed, 11 insertions(+), 9 deletions(-) diff --git a/doc/en/explanation/goodpractices.rst b/doc/en/explanation/goodpractices.rst index 4594e3a7d7b..e628185413a 100644 --- a/doc/en/explanation/goodpractices.rst +++ b/doc/en/explanation/goodpractices.rst @@ -11,9 +11,16 @@ Install package in a virtual environment For development, we recommend that you install your application, its dependencies and the ``pytest`` package itself into a virtual environment. -This ensures your code and dependencies are isolated from your system Python installation, -and avoids the ``externally-managed-environment`` error (:pep:`668`) -that many operating systems raise for installs into their own Python. +This ensures your code and dependencies are isolated from your system Python installation. + +.. note:: + + Many systems, such as recent Debian, Ubuntu and Fedora releases, refuse a plain + ``pip install`` outside a virtual environment with + ``error: externally-managed-environment`` (see :pep:`668`). + Do not work around this with ``--break-system-packages``, + which can break tools of your operating system; + create a virtual environment instead. Create a ``pyproject.toml`` file in the root of your repository as described in :doc:`packaging:tutorials/packaging-projects`. diff --git a/doc/en/getting-started.rst b/doc/en/getting-started.rst index 02b4741dc47..db2d446805d 100644 --- a/doc/en/getting-started.rst +++ b/doc/en/getting-started.rst @@ -10,12 +10,7 @@ Install ``pytest`` ---------------------------------------- Install ``pytest`` into a virtual environment, not into the Python installation -of your operating system. -Many systems, such as recent Debian, Ubuntu and Fedora releases, refuse a plain -``pip install`` outside a virtual environment with -``error: externally-managed-environment`` (see :pep:`668`). -Do not work around this with ``--break-system-packages``; -create a virtual environment instead. +of your operating system (see :ref:`install-package-with-pip`). 1. Create a virtual environment and install ``pytest`` into it, using the tool of your choice: From 48eeaf90a0eb47c94f4e737d643c76c889227145 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 25 Oct 2026 17:06:44 +0000 Subject: [PATCH 3/3] docs: mention using pytest from the operating system Some projects intentionally use the distribution's pytest instead of a virtual environment; describe that case separately from the default recommendation, as discussed in review. Co-Authored-By: Claude Opus 5.5 (1M context) --- doc/en/explanation/goodpractices.rst | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/doc/en/explanation/goodpractices.rst b/doc/en/explanation/goodpractices.rst index e628185413a..5e5a9bdfc84 100644 --- a/doc/en/explanation/goodpractices.rst +++ b/doc/en/explanation/goodpractices.rst @@ -82,6 +82,19 @@ together with the ``dev`` group, by running from the same directory: which lets you change your source code (both tests and application) and rerun tests at will. +.. _`system-pytest`: + +Using pytest from the operating system +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Some projects deliberately use the ``pytest`` provided by the operating system, +for example to test software that is itself built and packaged by a distribution, +or where a test suite only needs ``pytest`` to be available as a command. +In that case install ``pytest`` with the system package manager +(for example ``apt install python3-pytest`` or ``dnf install python3-pytest``), +not with ``pip`` into the system Python. +The version is then the one your distribution ships, which may be older than the latest release. + .. _`test discovery`: .. _`Python test discovery`: