44Good 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.
1314This 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+
1525Create a ``pyproject.toml `` file in the root of your repository as described in
1626:doc: `packaging:tutorials/packaging-projects `.
1727The 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
0 commit comments