| 1 |
############## |
| 2 |
Installation |
| 3 |
############## |
| 4 |
|
| 5 |
********* |
| 6 |
As tool |
| 7 |
********* |
| 8 |
|
| 9 |
:pypi:`tox` is a CLI tool that needs a Python interpreter (version 3.10 or higher) to run. We recommend either |
| 10 |
:pypi:`pipx` or :pypi:`uv` to install tox into an isolated environment. This has the added benefit that later you'll be |
| 11 |
able to upgrade tox without affecting other parts of the system. We provide method for ``pip`` too here but we |
| 12 |
discourage that path if you can: |
| 13 |
|
| 14 |
.. tab:: uv |
| 15 |
|
| 16 |
.. code-block:: bash |
| 17 |
|
| 18 |
# install uv per https://docs.astral.sh/uv/#getting-started |
| 19 |
uv tool install tox |
| 20 |
tox --help |
| 21 |
|
| 22 |
.. tab:: pipx |
| 23 |
|
| 24 |
.. code-block:: bash |
| 25 |
|
| 26 |
python -m pip install pipx-in-pipx --user |
| 27 |
pipx install tox |
| 28 |
tox --help |
| 29 |
|
| 30 |
.. tab:: pip |
| 31 |
|
| 32 |
.. code-block:: bash |
| 33 |
|
| 34 |
python -m pip install --user tox |
| 35 |
python -m tox --help |
| 36 |
|
| 37 |
You can install it within the global Python interpreter itself (perhaps as a user package via the |
| 38 |
``--user`` flag). Be cautious if you are using a Python installation that is managed by your operating system or |
| 39 |
another package manager. ``pip`` might not coordinate with those tools, and may leave your system in an inconsistent |
| 40 |
state. |
| 41 |
|
| 42 |
**Requirements:** |
| 43 |
|
| 44 |
- **wheel (default):** Installing tox via a wheel requires pip that understands the ``python-requires`` tag (see |
| 45 |
:PEP:`503`). With pip this is version ``9.0.0`` or later (released November 2016). If installing from a mirror, |
| 46 |
ensure it forwards the ``python-requires`` tag (notably OpenStack mirrors don't, and older :gh_repo:`devpi/devpi` |
| 47 |
versions before ``4.7.0`` don't). |
| 48 |
|
| 49 |
.. _sdist: |
| 50 |
|
| 51 |
- **sdist:** When installing via a source distribution you need pip that handles :PEP:`517`. With pip this is |
| 52 |
version ``18.0.0`` or later (released July 2018). If you cannot upgrade pip, ensure the build requirements from |
| 53 |
:gh:`pyproject.toml <tox-dev/tox/blob/main/pyproject.toml>` are satisfied before installation. |
| 54 |
|
| 55 |
******************* |
| 56 |
latest unreleased |
| 57 |
******************* |
| 58 |
|
| 59 |
Installing an unreleased version is discouraged and should be only done for testing purposes: |
| 60 |
|
| 61 |
.. tab:: uv |
| 62 |
|
| 63 |
.. code-block:: bash |
| 64 |
|
| 65 |
uv tool install --from git+https://github.com/tox-dev/tox.git@main tox |
| 66 |
|
| 67 |
.. tab:: pipx |
| 68 |
|
| 69 |
.. code-block:: bash |
| 70 |
|
| 71 |
pipx install git+https://github.com/tox-dev/tox.git@main |
| 72 |
|
| 73 |
.. tab:: pip |
| 74 |
|
| 75 |
.. code-block:: bash |
| 76 |
|
| 77 |
pip install git+https://github.com/tox-dev/tox.git@main |
| 78 |
|
| 79 |
Requires pip version ``18.0.0`` or later. |
| 80 |
|
| 81 |
For Python version compatibility, see :ref:`compatibility-requirements`. |
| 82 |
|
| 83 |
****************** |
| 84 |
Man Page Support |
| 85 |
****************** |
| 86 |
|
| 87 |
tox ships a compiled man page in its wheel. When installing tox: |
| 88 |
|
| 89 |
- **System-wide** (``sudo pip install tox``): Installs to ``/usr/share/man/man1/tox.1`` automatically |
| 90 |
- **User install** (``pip install --user tox``): Installs to ``~/.local/share/man/man1/tox.1`` automatically |
| 91 |
- **Package managers** (apt, brew, dnf): Install to the appropriate system location |
| 92 |
|
| 93 |
For user installs, ensure ``~/.local/share/man`` is in your ``MANPATH``: |
| 94 |
|
| 95 |
.. code-block:: bash |
| 96 |
|
| 97 |
# Add to ~/.bashrc or ~/.zshrc |
| 98 |
export MANPATH="$HOME/.local/share/man:$MANPATH" |
| 99 |
|
| 100 |
After updating your profile, restart your shell or run ``source ~/.bashrc``. |
| 101 |
|
| 102 |
Virtual Environment Installations |
| 103 |
================================= |
| 104 |
|
| 105 |
When tox is installed in a virtual environment (via pipx, uv tool, or venv), the man page is installed but not on the |
| 106 |
system ``MANPATH``. Use the ``tox man`` command to set it up: |
| 107 |
|
| 108 |
.. code-block:: bash |
| 109 |
|
| 110 |
tox man |
| 111 |
|
| 112 |
Building from Source |
| 113 |
==================== |
| 114 |
|
| 115 |
The man page is compiled from ``docs/man/tox.1.rst`` during wheel build. To regenerate the RST source after CLI changes: |
| 116 |
|
| 117 |
.. code-block:: bash |
| 118 |
|
| 119 |
tox run -e manpage |
| 120 |
|
| 121 |
After installation, view with ``man tox``. |