Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelog/15242.doc.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
The :ref:`installation instructions <installation>` 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.
73 changes: 66 additions & 7 deletions doc/en/explanation/goodpractices.rst
Original file line number Diff line number Diff line change
Expand Up @@ -4,14 +4,24 @@
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.
For development, we recommend that you install your application, its dependencies
and the ``pytest`` package itself into a virtual environment.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I know places which prefer to use pytest itself from the operating system package.

For a public example, I recently saw that PostgreSQL is considering using pytest: https://www.postgresql.org/message-id/DKSSP47Y857Z.1FUU91WMDZWPZ@jeltef.nl
And they rightly don't intend to use a venv, just expect pytest to be available as command.

But, I'm saying this not to change the recommendation, I think the text is fine. Just some subtlety :)

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i think that subtle part needs a note somewhere - not necessaryly under the default recommendation for most users

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 Written by Claude Opus 5.5 via Claude Code for the pytest maintainers; I prompted it, it did the work, I read it.

Added in 48eeaf9 as a separate "Using pytest from the operating system" subsection after the venv install steps, so the default recommendation stays unchanged: it covers projects that rely on the distribution's pytest, says to install it via the system package manager (e.g. apt/dnf install python3-pytest) rather than pip into the system Python, and notes the version may lag the latest release.


Generated by Claude Code

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`.
The first few lines should look like this:
Expand All @@ -26,16 +36,65 @@ 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 <packaging:specifications/dependency-groups>` 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:index>`
(``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

pip install -e .
`uv <https://docs.astral.sh/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 <virtualenv:index>`:

.. code-block:: bash
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.

.. _`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`:

Expand Down
45 changes: 42 additions & 3 deletions doc/en/getting-started.rst
Original file line number Diff line number Diff line change
Expand Up @@ -9,11 +9,47 @@ 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 (see :ref:`install-package-with-pip`).

.. 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 <pip:index>` 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 <https://docs.astral.sh/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 <virtualenv:index>` 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:

Expand All @@ -22,6 +58,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
Expand Down
Loading