| 1 |
.. _getting_started: |
| 2 |
|
| 3 |
################# |
| 4 |
Getting Started |
| 5 |
################# |
| 6 |
|
| 7 |
This tutorial walks you through creating your first tox project from scratch. By the end, you will have a working tox |
| 8 |
configuration that runs tests and linting across multiple Python versions. |
| 9 |
|
| 10 |
*************** |
| 11 |
Prerequisites |
| 12 |
*************** |
| 13 |
|
| 14 |
Before starting, make sure you have: |
| 15 |
|
| 16 |
- Python 3.10 or later installed |
| 17 |
- tox installed (see :doc:`../how-to/install`) |
| 18 |
- A Python project you want to test (or follow along to create one) |
| 19 |
|
| 20 |
Verify tox is available: |
| 21 |
|
| 22 |
.. code-block:: bash |
| 23 |
|
| 24 |
tox --version |
| 25 |
|
| 26 |
*********************************** |
| 27 |
Creating your first configuration |
| 28 |
*********************************** |
| 29 |
|
| 30 |
tox needs a configuration file where you define what tools to run and how to set up environments for them. tox supports |
| 31 |
two configuration formats: TOML and INI. **TOML is the recommended format for new projects** -- it is more robust, has |
| 32 |
proper type support, and avoids ambiguities inherent in INI parsing. INI remains supported for existing projects. |
| 33 |
|
| 34 |
Create a ``tox.toml`` (or ``tox.ini``) at the root of your project: |
| 35 |
|
| 36 |
.. tab:: TOML |
| 37 |
|
| 38 |
.. code-block:: toml |
| 39 |
|
| 40 |
env_list = ["3.13", "3.12", "lint"] |
| 41 |
|
| 42 |
[env_run_base] |
| 43 |
description = "run the test suite with pytest" |
| 44 |
deps = [ |
| 45 |
"pytest>=8", |
| 46 |
] |
| 47 |
commands = [["pytest", { replace = "posargs", default = ["tests"], extend = true }]] |
| 48 |
|
| 49 |
[env.lint] |
| 50 |
description = "run linters" |
| 51 |
skip_install = true |
| 52 |
deps = ["ruff"] |
| 53 |
commands = [["ruff", "check", { replace = "posargs", default = ["."], extend = true }]] |
| 54 |
|
| 55 |
.. tab:: INI |
| 56 |
|
| 57 |
.. code-block:: ini |
| 58 |
|
| 59 |
[tox] |
| 60 |
env_list = 3.13, 3.12, lint |
| 61 |
|
| 62 |
[testenv] |
| 63 |
description = run the test suite with pytest |
| 64 |
deps = |
| 65 |
pytest>=8 |
| 66 |
commands = |
| 67 |
pytest {posargs:tests} |
| 68 |
|
| 69 |
[testenv:lint] |
| 70 |
description = run linters |
| 71 |
skip_install = true |
| 72 |
deps = |
| 73 |
ruff |
| 74 |
commands = ruff check {posargs:.} |
| 75 |
|
| 76 |
.. tip:: |
| 77 |
|
| 78 |
You can also generate a ``tox.ini`` file automatically by running ``tox quickstart`` and answering a few questions. |
| 79 |
|
| 80 |
********************************* |
| 81 |
Understanding the configuration |
| 82 |
********************************* |
| 83 |
|
| 84 |
The configuration has two parts: **core settings** and **environment settings**. |
| 85 |
|
| 86 |
Core settings |
| 87 |
============= |
| 88 |
|
| 89 |
Core settings affect all environments or configure how tox itself behaves. They live at the root level in ``tox.toml`` |
| 90 |
(or under the ``[tox]`` section in ``tox.ini``). |
| 91 |
|
| 92 |
.. tab:: TOML |
| 93 |
|
| 94 |
.. code-block:: toml |
| 95 |
|
| 96 |
env_list = ["3.13", "3.12", "lint"] |
| 97 |
|
| 98 |
.. tab:: INI |
| 99 |
|
| 100 |
.. code-block:: ini |
| 101 |
|
| 102 |
[tox] |
| 103 |
env_list = 3.13, 3.12, lint |
| 104 |
|
| 105 |
The :ref:`env_list` setting defines which environments run by default when you invoke ``tox`` without specifying any. |
| 106 |
Both formats support generating environment matrices from factor combinations — INI uses curly-brace expansion |
| 107 |
(``3.{10-}``), while TOML composes from structured dicts. A single axis is a bare range dict (``{ prefix = "3.", start = |
| 108 |
10 }``); multi-dimensional matrices use a ``product`` dict. See :ref:`generative-environment-list` for details. For the |
| 109 |
full list of core options, see :ref:`conf-core`. |
| 110 |
|
| 111 |
Environment settings |
| 112 |
==================== |
| 113 |
|
| 114 |
Each tox environment has its own configuration. Settings defined at the base level (``env_run_base`` in TOML, |
| 115 |
``testenv`` in INI) are inherited by all environments unless overridden. Individual environments are configured under |
| 116 |
``env.<name>`` in TOML or ``testenv:<name>`` in INI. |
| 117 |
|
| 118 |
.. tab:: TOML |
| 119 |
|
| 120 |
.. code-block:: toml |
| 121 |
|
| 122 |
[env_run_base] |
| 123 |
description = "run the test suite with pytest" |
| 124 |
deps = ["pytest>=8"] |
| 125 |
commands = [["pytest", { replace = "posargs", default = ["tests"], extend = true }]] |
| 126 |
|
| 127 |
[env.lint] |
| 128 |
description = "run linters" |
| 129 |
skip_install = true |
| 130 |
deps = ["ruff"] |
| 131 |
commands = [["ruff", "check", "."]] |
| 132 |
|
| 133 |
.. tab:: INI |
| 134 |
|
| 135 |
.. code-block:: ini |
| 136 |
|
| 137 |
[testenv] |
| 138 |
description = run the test suite with pytest |
| 139 |
deps = |
| 140 |
pytest>=8 |
| 141 |
commands = |
| 142 |
pytest {posargs:tests} |
| 143 |
|
| 144 |
[testenv:lint] |
| 145 |
description = run linters |
| 146 |
skip_install = true |
| 147 |
deps = |
| 148 |
ruff |
| 149 |
commands = ruff check . |
| 150 |
|
| 151 |
Here the ``lint`` environment overrides the base settings entirely, while ``3.13`` and ``3.12`` inherit from the base. |
| 152 |
|
| 153 |
.. tip:: |
| 154 |
|
| 155 |
Options must go in the correct section — placing a core option in an environment section (or vice versa) silently |
| 156 |
has no effect. Run ``tox run -v`` or ``tox config`` to check for misplaced keys. |
| 157 |
|
| 158 |
Environment names and Python versions |
| 159 |
===================================== |
| 160 |
|
| 161 |
Environment names can consist of alphanumeric characters, dashes, and dots. Names are split on dashes into **factors** |
| 162 |
-- for example ``py311-django42`` splits into factors ``py311`` and ``django42``. Additionally, the current platform |
| 163 |
(like ``linux``, ``darwin``, ``win32``) is automatically available as an implicit factor for conditional configuration. |
| 164 |
|
| 165 |
tox recognizes certain naming patterns and automatically sets the Python interpreter: |
| 166 |
|
| 167 |
- ``N.M``: CPython N.M (e.g. ``3.13``) -- **preferred** |
| 168 |
- ``pyNM`` or ``pyN.M``: CPython N.M (e.g. ``py313`` or ``py3.13``) -- legacy, still supported |
| 169 |
- ``pypyNM``: PyPy N.M |
| 170 |
- ``cpythonNM``: CPython N.M |
| 171 |
- ``graalpyNM``: GraalPy N.M |
| 172 |
|
| 173 |
Prefer the ``N.M`` form (e.g. ``3.14``) over ``pyNMM`` (e.g. ``py314``). The dotted form is unambiguous, reads more |
| 174 |
naturally in environment lists and CI output, and avoids confusion for Python versions >= 3.10 where the concatenated |
| 175 |
digits become three characters. |
| 176 |
|
| 177 |
.. note:: |
| 178 |
|
| 179 |
Version-number factors like ``3.14`` can be checked in conditional expressions using subscript syntax: |
| 180 |
``factor['3.14']`` (the dot-syntax ``factor.3.14`` would be a syntax error). See :ref:`conditional-value-reference` |
| 181 |
for details. |
| 182 |
|
| 183 |
If the name doesn't match any pattern, tox uses the same Python as the one tox is installed into (this is the case for |
| 184 |
``lint`` in our example). To override this fallback, set :ref:`default_base_python`: |
| 185 |
|
| 186 |
.. code-block:: toml |
| 187 |
|
| 188 |
[env_run_base] |
| 189 |
default_base_python = ["3.14", "3.13"] |
| 190 |
|
| 191 |
This pins a default Python version for environments without a Python factor, improving reproducibility across machines |
| 192 |
with different system Pythons. |
| 193 |
|
| 194 |
.. tip:: |
| 195 |
|
| 196 |
If your project uses :PEP:`751` lock files (``pylock.toml``), you can install locked dependencies via :ref:`pylock` |
| 197 |
instead of listing packages in ``deps``. |
| 198 |
|
| 199 |
For the full list of environment options, see :ref:`conf-testenv`. |
| 200 |
|
| 201 |
Scaling to multiple Python versions |
| 202 |
=================================== |
| 203 |
|
| 204 |
When your test matrix grows beyond a few environments, use ``env_base`` sections to define named templates that generate |
| 205 |
environments from factor combinations: |
| 206 |
|
| 207 |
.. code-block:: toml |
| 208 |
|
| 209 |
[env_base.test] |
| 210 |
factors = [["3.13", "3.14"]] |
| 211 |
deps = ["pytest>=8"] |
| 212 |
commands = [["pytest"]] |
| 213 |
|
| 214 |
This generates ``test-3.13`` and ``test-3.14``, each inheriting deps and commands from the template. The template itself |
| 215 |
inherits from ``env_run_base``, so global defaults still apply. See :ref:`env-base-templates` for details. |
| 216 |
|
| 217 |
*************************** |
| 218 |
Running your environments |
| 219 |
*************************** |
| 220 |
|
| 221 |
Run all default environments (those listed in :ref:`env_list`): |
| 222 |
|
| 223 |
.. code-block:: bash |
| 224 |
|
| 225 |
tox |
| 226 |
|
| 227 |
Run a specific environment: |
| 228 |
|
| 229 |
.. code-block:: bash |
| 230 |
|
| 231 |
tox run -e lint |
| 232 |
|
| 233 |
Run multiple environments: |
| 234 |
|
| 235 |
.. code-block:: bash |
| 236 |
|
| 237 |
tox run -e 3.13,lint |
| 238 |
|
| 239 |
Pass extra arguments to the underlying tool using ``--``: |
| 240 |
|
| 241 |
.. code-block:: bash |
| 242 |
|
| 243 |
# Run pytest in verbose mode |
| 244 |
tox run -e 3.13 -- -v |
| 245 |
|
| 246 |
# Run ruff on a specific file |
| 247 |
tox run -e lint -- src/mymodule.py |
| 248 |
|
| 249 |
The ``{ replace = "posargs" }`` in TOML (or ``{posargs}`` in INI) is a placeholder that gets replaced by whatever you |
| 250 |
pass after ``--``. |
| 251 |
|
| 252 |
************************** |
| 253 |
Understanding the output |
| 254 |
************************** |
| 255 |
|
| 256 |
On the first run, tox creates virtual environments and installs dependencies. Subsequent runs reuse existing |
| 257 |
environments unless dependencies change: |
| 258 |
|
| 259 |
.. code-block:: bash |
| 260 |
|
| 261 |
$ tox run -e 3.13,lint |
| 262 |
3.13: install_deps> python -m pip install 'pytest>=8' |
| 263 |
3.13: commands[0]> pytest tests |
| 264 |
========================= 3 passed in 0.12s ========================= |
| 265 |
3.13: OK ✔ in 5.43s |
| 266 |
lint: install_deps> python -m pip install ruff |
| 267 |
lint: commands[0]> ruff check . |
| 268 |
All checks passed! |
| 269 |
lint: OK ✔ in 2.11s |
| 270 |
|
| 271 |
3.13: OK (5.43=setup[3.21]+cmd[2.22] seconds) |
| 272 |
lint: OK (2.11=setup[1.05]+cmd[1.06] seconds) |
| 273 |
congratulations :) |
| 274 |
|
| 275 |
tox will automatically detect changes to your dependencies and recreate environments when needed. You can force a full |
| 276 |
recreation with the ``-r`` flag: |
| 277 |
|
| 278 |
.. code-block:: bash |
| 279 |
|
| 280 |
tox run -e 3.13 -r |
| 281 |
|
| 282 |
If tools inside the environment maintain their own caches (e.g. pre-commit), you can use :ref:`recreate_commands` to |
| 283 |
clean them before the environment directory is removed. See :ref:`howto_clean_caches` for details. |
| 284 |
|
| 285 |
If you want to rerun tests without reinstalling dependencies or the package (e.g. when working offline or when nothing |
| 286 |
has changed), use ``--skip-env-install``: |
| 287 |
|
| 288 |
.. code-block:: bash |
| 289 |
|
| 290 |
tox run -e 3.13 --skip-env-install |
| 291 |
|
| 292 |
******************************** |
| 293 |
Listing available environments |
| 294 |
******************************** |
| 295 |
|
| 296 |
See all configured environments and their descriptions: |
| 297 |
|
| 298 |
.. code-block:: bash |
| 299 |
|
| 300 |
$ tox list |
| 301 |
default environments: |
| 302 |
3.13 -> run the test suite with pytest |
| 303 |
3.12 -> run the test suite with pytest |
| 304 |
lint -> run linters |
| 305 |
|
| 306 |
************************** |
| 307 |
Inspecting configuration |
| 308 |
************************** |
| 309 |
|
| 310 |
View the resolved configuration for an environment: |
| 311 |
|
| 312 |
.. code-block:: bash |
| 313 |
|
| 314 |
tox config -e 3.13 -k deps commands |
| 315 |
|
| 316 |
The output format can be changed with ``--format`` and written to a file with ``-o``: |
| 317 |
|
| 318 |
.. code-block:: bash |
| 319 |
|
| 320 |
tox config -e 3.13 --format json -o config.json |
| 321 |
tox config -e 3.13 --format toml -o config.toml |
| 322 |
|
| 323 |
This is useful for debugging configuration issues and for programmatic consumption. |
| 324 |
|
| 325 |
************ |
| 326 |
Next steps |
| 327 |
************ |
| 328 |
|
| 329 |
Now that you have a working tox setup, explore these topics: |
| 330 |
|
| 331 |
- :doc:`../explanation` -- understand how tox works (parallel mode, packaging, auto-provisioning) |
| 332 |
- :doc:`../how-to/usage` -- practical recipes for common tasks (including testing across old and new Python versions |
| 333 |
with :ref:`virtualenv_spec`) |
| 334 |
- :ref:`configuration` -- full configuration reference |
| 335 |
- :ref:`cli` -- complete CLI reference |
| 336 |
- :ref:`howto_pep723` -- run standalone scripts with inline dependencies (:PEP:`723`) |