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..5e5a9bdfc84 100644 --- a/doc/en/explanation/goodpractices.rst +++ b/doc/en/explanation/goodpractices.rst @@ -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. 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: @@ -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 ` 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 - pip install -e . + `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 + + 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`: diff --git a/doc/en/getting-started.rst b/doc/en/getting-started.rst index f8deae77e3e..db2d446805d 100644 --- a/doc/en/getting-started.rst +++ b/doc/en/getting-started.rst @@ -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 ` 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 +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