Skip to content

Commit a7b2446

Browse files
Merge pull request #15245 from pytest-dev/claude/project-thread-9jcf91
docs: show venv/pip, uv and virtualenv installs
2 parents 679d09c + 48eeaf9 commit a7b2446

3 files changed

Lines changed: 109 additions & 10 deletions

File tree

‎changelog/15242.doc.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
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.

‎doc/en/explanation/goodpractices.rst‎

Lines changed: 66 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -4,14 +4,24 @@
44
Good Integration Practices
55
=================================================
66

7-
Install package with pip
7+
.. _`install-package-with-pip`:
8+
9+
Install package in a virtual environment
810
-------------------------------------------------
911

10-
For development, we recommend you use :mod:`venv` for virtual environments and
11-
:doc:`pip:index` for installing your application and any dependencies,
12-
as well as the ``pytest`` package itself.
12+
For development, we recommend that you install your application, its dependencies
13+
and the ``pytest`` package itself into a virtual environment.
1314
This ensures your code and dependencies are isolated from your system Python installation.
1415

16+
.. note::
17+
18+
Many systems, such as recent Debian, Ubuntu and Fedora releases, refuse a plain
19+
``pip install`` outside a virtual environment with
20+
``error: externally-managed-environment`` (see :pep:`668`).
21+
Do not work around this with ``--break-system-packages``,
22+
which can break tools of your operating system;
23+
create a virtual environment instead.
24+
1525
Create a ``pyproject.toml`` file in the root of your repository as described in
1626
:doc:`packaging:tutorials/packaging-projects`.
1727
The first few lines should look like this:
@@ -26,16 +36,65 @@ The first few lines should look like this:
2636
name = "PACKAGENAME"
2737
version = "PACKAGEVERSION"
2838
39+
[dependency-groups]
40+
dev = ["pytest"]
41+
2942
where ``PACKAGENAME`` and ``PACKAGEVERSION`` are the name and version of your package respectively.
43+
The ``dev`` :doc:`dependency group <packaging:specifications/dependency-groups>` lists the
44+
tools you need for development, such as ``pytest``.
3045

31-
You can then install your package in "editable" mode by running from the same directory:
46+
You can then create a virtual environment and install your package in "editable" mode,
47+
together with the ``dev`` group, by running from the same directory:
3248

33-
.. code-block:: bash
49+
.. tab:: venv + pip
50+
51+
Uses :mod:`venv` and :doc:`pip <pip:index>`
52+
(``pip install --group`` needs pip 25.1 or newer):
53+
54+
.. code-block:: bash
55+
56+
python3 -m venv .venv
57+
source .venv/bin/activate # on Windows: .venv\Scripts\activate
58+
pip install -e . --group dev
59+
pytest
60+
61+
.. tab:: uv
3462

35-
pip install -e .
63+
`uv <https://docs.astral.sh/uv/>`__ creates ``.venv``, installs your
64+
package in editable mode and installs the ``dev`` group by default:
65+
66+
.. code-block:: bash
67+
68+
uv sync
69+
uv run pytest
70+
71+
.. tab:: virtualenv
72+
73+
Same as with :mod:`venv`, but the environment is created by
74+
:doc:`virtualenv <virtualenv:index>`:
75+
76+
.. code-block:: bash
77+
78+
virtualenv .venv
79+
source .venv/bin/activate # on Windows: .venv\Scripts\activate
80+
pip install -e . --group dev
81+
pytest
3682
3783
which lets you change your source code (both tests and application) and rerun tests at will.
3884

85+
.. _`system-pytest`:
86+
87+
Using pytest from the operating system
88+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
89+
90+
Some projects deliberately use the ``pytest`` provided by the operating system,
91+
for example to test software that is itself built and packaged by a distribution,
92+
or where a test suite only needs ``pytest`` to be available as a command.
93+
In that case install ``pytest`` with the system package manager
94+
(for example ``apt install python3-pytest`` or ``dnf install python3-pytest``),
95+
not with ``pip`` into the system Python.
96+
The version is then the one your distribution ships, which may be older than the latest release.
97+
3998
.. _`test discovery`:
4099
.. _`Python test discovery`:
41100

‎doc/en/getting-started.rst‎

Lines changed: 42 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -9,11 +9,47 @@ Get Started
99
Install ``pytest``
1010
----------------------------------------
1111

12-
1. Run the following command in your command line:
12+
Install ``pytest`` into a virtual environment, not into the Python installation
13+
of your operating system (see :ref:`install-package-with-pip`).
1314

14-
.. code-block:: bash
15+
1. Create a virtual environment and install ``pytest`` into it,
16+
using the tool of your choice:
17+
18+
.. tab:: venv + pip
19+
20+
:mod:`venv` and :doc:`pip <pip:index>` ship with Python.
21+
Some Linux distributions package them separately
22+
(for example ``python3-venv`` on Debian and Ubuntu).
23+
24+
.. code-block:: bash
25+
26+
python3 -m venv .venv
27+
source .venv/bin/activate # on Windows: .venv\Scripts\activate
28+
pip install -U pytest
29+
30+
.. tab:: uv
31+
32+
`uv <https://docs.astral.sh/uv/>`__ creates and manages the virtual
33+
environment of your project for you.
34+
In a directory with a ``pyproject.toml`` (``uv init`` creates one):
1535

16-
pip install -U pytest
36+
.. code-block:: bash
37+
38+
uv add --dev pytest
39+
40+
Prefix the ``pytest`` commands on this page with ``uv run``,
41+
for example ``uv run pytest``, to run them inside the project environment.
42+
43+
.. tab:: virtualenv
44+
45+
:doc:`virtualenv <virtualenv:index>` is a faster, more configurable
46+
alternative to :mod:`venv`:
47+
48+
.. code-block:: bash
49+
50+
virtualenv .venv
51+
source .venv/bin/activate # on Windows: .venv\Scripts\activate
52+
pip install -U pytest
1753
1854
2. Check that you installed the correct version:
1955

@@ -22,6 +58,9 @@ Install ``pytest``
2258
$ pytest --version
2359
pytest 9.1.1
2460
61+
See :ref:`install-package-with-pip` for how to install the project you are
62+
testing into the same environment.
63+
2564
.. _`simpletest`:
2665

2766
Create your first test

0 commit comments

Comments
 (0)