Debian Codegraph @

docs/how-to/install.rst

raw
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``.