Debian Codegraph @

docs/how-to/usage.rst

raw
1 .. _howto:
2
3 ###############
4 How-to Guides
5 ###############
6
7 Practical recipes for common tox tasks. Each section answers a specific "How do I...?" question.
8
9 *****************
10 Quick reference
11 *****************
12
13 Common commands
14 ===============
15
16 - Each tox subcommand has a 1 (or 2) letter shortcut, e.g. ``tox run`` = ``tox r``, ``tox config`` = ``tox c``.
17 - Run all default environments: ``tox`` (runs everything in :ref:`env_list`).
18 - Run a specific environment: ``tox run -e 3.13``.
19 - Run multiple environments: ``tox run -e lint,3.13`` (sequential, in order).
20 - Run environments in parallel: ``tox parallel -e 3.13,3.12`` (see :ref:`parallel_mode`).
21 - Run all environments matching a label: ``tox run -m test`` (see :ref:`labels`).
22 - Run all environments matching a factor: ``tox run -f django`` (runs all envs containing the ``django`` factor).
23 - Inspect configuration: ``tox config -e 3.13 -k pass_env``.
24 - Force recreation: ``tox run -e 3.13 -r``.
25
26 Environment variables
27 =====================
28
29 - View environment variables: ``tox c -e 3.13 -k set_env pass_env``.
30 - Pass through system environment variables: use :ref:`pass_env`.
31 - Set environment variables: use :ref:`set_env`.
32 - Setup commands: :ref:`commands_pre`. Teardown commands: :ref:`commands_post`.
33 - Change working directory: :ref:`change_dir` (affects install commands too if using relative paths).
34
35 Logging
36 =======
37
38 tox logs command invocations inside ``.tox/<env_name>/log``. Environment variables with names containing sensitive words
39 (``access``, ``api``, ``auth``, ``client``, ``cred``, ``key``, ``passwd``, ``password``, ``private``, ``pwd``,
40 ``secret``, ``token``) are logged with their values redacted to prevent accidental secret leaking in CI/CD environments.
41
42 .. ------------------------------------------------------------------------------------------
43
44 .. Testing & Verification (most common workflows)
45
46 .. ------------------------------------------------------------------------------------------
47
48 ******************
49 Test with pytest
50 ******************
51
52 A typical pytest configuration:
53
54 .. tab:: TOML
55
56 .. code-block:: toml
57
58 env_list = ["3.13", "3.12"]
59
60 [env_run_base]
61 deps = ["pytest>=8"]
62 commands = [["pytest", { replace = "posargs", default = ["tests"], extend = true }]]
63
64 .. tab:: INI
65
66 .. code-block:: ini
67
68 [tox]
69 env_list = 3.13, 3.12
70
71 [testenv]
72 deps = pytest>=8
73 commands = pytest {posargs:tests}
74
75 When running tox in parallel mode, ensure each pytest invocation is fully isolated by setting a unique temporary
76 directory:
77
78 .. tab:: TOML
79
80 .. code-block:: toml
81
82 [env_run_base]
83 commands = [["pytest", "--basetemp={env_tmp_dir}", { replace = "posargs", default = ["tests"], extend = true }]]
84
85 .. tab:: INI
86
87 .. code-block:: ini
88
89 [testenv]
90 commands = pytest --basetemp="{env_tmp_dir}" {posargs:tests}
91
92 ***********************************************
93 Collect coverage across multiple environments
94 ***********************************************
95
96 A common pattern is running tests across several Python versions and combining coverage results. Use :ref:`depends` to
97 ensure coverage runs after all test environments:
98
99 .. tab:: TOML
100
101 .. code-block:: toml
102
103 env_list = ["3.13", "3.12", "coverage"]
104
105 [env_run_base]
106 deps = ["pytest", "coverage[toml]"]
107 commands = [["coverage", "run", "-p", "-m", "pytest", "tests"]]
108
109 [env.coverage]
110 skip_install = true
111 deps = ["coverage[toml]"]
112 depends = ["3.*"]
113 commands = [
114 ["coverage", "combine"],
115 ["coverage", "report", "--fail-under=80"],
116 ]
117
118 .. tab:: INI
119
120 .. code-block:: ini
121
122 [tox]
123 env_list = 3.13, 3.12, coverage
124
125 [testenv]
126 deps =
127 pytest
128 coverage[toml]
129 commands = coverage run -p -m pytest tests
130
131 [testenv:coverage]
132 skip_install = true
133 deps = coverage[toml]
134 depends = 3.*
135 commands =
136 coverage combine
137 coverage report --fail-under=80
138
139 The ``-p`` flag (parallel mode) creates separate ``.coverage.<hash>`` files per environment. ``coverage combine`` merges
140 them before generating the report.
141
142 .. _tox-exec:
143
144 **********************************
145 Run a one-off command (tox exec)
146 **********************************
147
148 The ``tox exec`` subcommand runs an arbitrary command inside a tox environment without executing the configured
149 ``commands``, ``commands_pre``, or ``commands_post``. It also skips package installation. Pass the command after ``--``:
150
151 .. code-block:: bash
152
153 # Open a Python shell inside the "3.13" environment
154 tox exec -e 3.13 -- python
155
156 # Check installed packages
157 tox exec -e 3.13 -- pip list
158
159 # Run a script with the environment's Python
160 tox exec -e 3.13 -- python scripts/migrate.py --dry-run
161
162 The command must be in the environment's ``PATH`` or listed in :ref:`allowlist_externals`. ``tox exec`` is useful for
163 debugging, running one-off scripts, or interactively exploring an environment without modifying your configuration.
164
165 .. ------------------------------------------------------------------------------------------
166
167 .. Configuration (frequently needed)
168
169 .. ------------------------------------------------------------------------------------------
170
171 *********************************
172 Override configuration defaults
173 *********************************
174
175 tox provides several ways to override configuration values without editing the configuration file.
176
177 **User-level configuration file**: tox reads a user-level config file whose location is shown in ``tox --help``. The
178 location can be changed via the ``TOX_CONFIG_FILE`` environment variable.
179
180 **Environment variables**: Any tox setting can be set via an environment variable with the ``TOX_`` prefix:
181
182 .. code-block:: bash
183
184 # Use wheel packaging
185 TOX_PACKAGE=wheel tox run -e 3.13
186
187 **CLI override**: The ``-x`` (or ``--override``) flag overrides any configuration value:
188
189 .. code-block:: bash
190
191 # Force editable install for a specific environment
192 tox run -e 3.13 -x "testenv:3.13.package=editable"
193
194 **********************************
195 Use labels to group environments
196 **********************************
197
198 Labels let you assign tags to environments and run them as a group with ``tox run -m <label>``:
199
200 .. tab:: TOML
201
202 .. code-block:: toml
203
204 env_list = ["3.13", "3.12", "lint", "type"]
205
206 [env_run_base]
207 labels = ["test"]
208 commands = [["pytest", "tests"]]
209
210 [env.lint]
211 labels = ["check"]
212 skip_install = true
213 deps = ["ruff"]
214 commands = [["ruff", "check", "."]]
215
216 [env.type]
217 labels = ["check"]
218 deps = ["mypy"]
219 commands = [["mypy", "src"]]
220
221 .. tab:: INI
222
223 .. code-block:: ini
224
225 [tox]
226 env_list = 3.13, 3.12, lint, type
227
228 [testenv]
229 labels = test
230 commands = pytest tests
231
232 [testenv:lint]
233 labels = check
234 skip_install = true
235 deps = ruff
236 commands = ruff check .
237
238 [testenv:type]
239 labels = check
240 deps = mypy
241 commands = mypy src
242
243 .. code-block:: bash
244
245 # Run all environments labeled "check"
246 tox run -m check
247
248 # Run all environments labeled "test"
249 tox run -m test
250
251 ********************************
252 Disallow unlisted environments
253 ********************************
254
255 By default, running ``tox -e <name>`` with an environment name not defined in the configuration still works -- tox
256 creates an environment with default settings. This can mask typos.
257
258 For example, given:
259
260 .. tab:: TOML
261
262 .. code-block:: toml
263
264 [env.unit]
265 deps = ["pytest"]
266 commands = [["pytest"]]
267
268 .. tab:: INI
269
270 .. code-block:: ini
271
272 [testenv:unit]
273 deps = pytest
274 commands = pytest
275
276 Running ``tox -e unt`` or ``tox -e unti`` would succeed without running any tests. An exception is made for environments
277 that look like Python version specifiers -- ``tox -e 3.13`` or ``tox -e py313`` would still work as intended.
278
279 Note that Python versions can be written with or without dots (``py3.10`` vs ``py310``). If you define ``py310-lint`` in
280 your configuration and accidentally run ``tox -e py3.10-lint``, tox will detect the mismatch and suggest the correct
281 environment name with a ``did you mean py310-lint?`` message rather than silently falling back to the base test
282 environment.
283
284 .. _platform-specification:
285
286 **************************************
287 Configure platform-specific settings
288 **************************************
289
290 Platform-dependent commands
291 ===========================
292
293 The current platform (``sys.platform`` value like ``linux``, ``darwin``, ``win32``) is automatically available as an
294 implicit factor in all environments. Use platform factors to run different commands or set different dependencies per
295 platform without encoding the platform name in the environment:
296
297 .. tab:: TOML
298
299 .. code-block:: toml
300
301 [env_list_base]
302 env_list = ["py313"]
303
304 [env_run_base]
305 deps = [
306 "pytest",
307 { replace = "if", condition = "factor.linux or factor.darwin", then = ["platformdirs>=3"], extend = true },
308 { replace = "if", condition = "factor.win32", then = ["platformdirs>=2"], extend = true },
309 ]
310 commands = [
311 { replace = "if", condition = "factor.linux", then = [["python", "-c", "print('Running on Linux')"]], extend = true },
312 { replace = "if", condition = "factor.darwin", then = [["python", "-c", "print('Running on macOS')"]], extend = true },
313 { replace = "if", condition = "factor.win32", then = [["python", "-c", "print('Running on Windows')"]], extend = true },
314 ["python", "-m", "pytest"],
315 ]
316
317 .. tab:: INI
318
319 .. code-block:: ini
320
321 [tox]
322 env_list = py313
323
324 [testenv]
325 deps =
326 pytest
327 linux,darwin: platformdirs>=3
328 win32: platformdirs>=2
329 commands =
330 linux: python -c 'print("Running on Linux")'
331 darwin: python -c 'print("Running on macOS")'
332 win32: python -c 'print("Running on Windows")'
333 python -m pytest
334
335 This allows a single environment like ``py313`` to adapt its behavior based on the execution platform. The platform
336 factors work alongside regular factors from the environment name.
337
338 Common ``sys.platform`` values:
339
340 - ``linux`` - Linux systems
341 - ``darwin`` - macOS systems
342 - ``win32`` - Windows systems (both 32-bit and 64-bit)
343 - ``cygwin`` - Cygwin on Windows
344 - ``freebsd13`` - FreeBSD 13.x (version varies)
345 - ``openbsd7`` - OpenBSD 7.x (version varies)
346
347 Platform factors with environment factors
348 =========================================
349
350 Platform factors combine with regular environment factors. For example, an environment named ``py313-django50`` has
351 factors ``py313``, ``django50``, and the current platform:
352
353 .. tab:: TOML
354
355 .. code-block:: toml
356
357 env_list = [
358 { product = [["py312", "py313"], ["django42", "django50"]] },
359 ]
360
361 [env_run_base]
362 deps = [
363 { replace = "if", condition = "factor.django42", then = ["Django>=4.2,<4.3"], extend = true },
364 { replace = "if", condition = "factor.django50", then = ["Django>=5.0,<5.1"], extend = true },
365 { replace = "if", condition = "factor.py312 and factor.linux", then = ["pytest-xdist"], extend = true },
366 { replace = "if", condition = "factor.darwin", then = ["pyobjc-framework-Cocoa"], extend = true },
367 ]
368 commands = [
369 { replace = "if", condition = "factor.win32", then = [["python", "-c", "import winreg"]], extend = true },
370 ["pytest"],
371 ]
372
373 .. tab:: INI
374
375 .. code-block:: ini
376
377 [tox]
378 env_list = py3{12,13}-django{42,50}
379
380 [testenv]
381 deps =
382 django42: Django>=4.2,<4.3
383 django50: Django>=5.0,<5.1
384 py312,linux: pytest-xdist # only on Python 3.12 + Linux
385 darwin: pyobjc-framework-Cocoa # only on macOS
386 commands =
387 win32: python -c 'import winreg' # only runs on Windows
388 pytest
389
390 Negation also works with platform factors:
391
392 .. tab:: TOML
393
394 .. code-block:: toml
395
396 [env_run_base]
397 deps = [
398 { replace = "if", condition = "not factor.win32", then = ["uvloop"], extend = true },
399 { replace = "if", condition = "not factor.darwin", then = ["pyinotify"], extend = true },
400 ]
401
402 .. tab:: INI
403
404 .. code-block:: ini
405
406 [testenv]
407 deps =
408 !win32: uvloop # install uvloop on non-Windows platforms
409 !darwin: pyinotify # install pyinotify except on macOS
410
411 Platform skipping vs platform factors
412 =====================================
413
414 There are two ways to handle platform differences:
415
416 **Platform factors** (recommended) - Filter individual settings per platform:
417
418 .. tab:: TOML
419
420 .. code-block:: toml
421
422 [env_run_base]
423 commands = [
424 { replace = "if", condition = "factor.linux", then = [["pytest", "--numprocesses=auto"]], extend = true },
425 { replace = "if", condition = "factor.darwin or factor.win32", then = [["pytest"]], extend = true },
426 ]
427
428 .. tab:: INI
429
430 .. code-block:: ini
431
432 [testenv]
433 commands =
434 linux: pytest --numprocesses=auto
435 darwin,win32: pytest
436
437 Settings without a platform factor apply to all platforms. This is ideal for most cross-platform projects.
438
439 **Platform skipping** - Skip entire environments when platform doesn't match:
440
441 .. tab:: TOML
442
443 .. code-block:: toml
444
445 [env_run_base]
446 platform = "linux"
447
448 .. tab:: INI
449
450 .. code-block:: ini
451
452 [testenv]
453 platform = linux
454
455 This skips the entire environment on non-Linux systems. Use this only when an environment genuinely cannot run on other
456 platforms (e.g., testing Linux-specific kernel features).
457
458 .. note::
459
460 Platform factors are supported in both INI and TOML formats. INI uses inline syntax (``linux: command``), while TOML
461 uses ``replace = "if"`` with ``factor.NAME`` conditions (see :ref:`conditional-value-reference`).
462
463 .. _howto_architecture:
464
465 Targeting a specific CPU architecture
466 =====================================
467
468 .. versionadded:: 4.46
469
470 On machines that support multiple CPU architectures (e.g. Apple Silicon running ``arm64`` natively and ``x86_64`` via
471 Rosetta 2, or Linux running ``aarch64`` and ``x86_64`` via ``qemu-user``), you can constrain tox environments to a
472 specific architecture by appending the ISA name to :ref:`base_python`.
473
474 The architecture is derived from :func:`python:sysconfig.get_platform` (e.g. ``macosx-14.0-arm64``, ``linux-x86_64``)
475 and normalized by :pypi:`virtualenv` (``amd64`` → ``x86_64``, ``aarch64`` → ``arm64``).
476
477 .. tab:: TOML
478
479 .. code-block:: toml
480
481 # Run tests on both arm64 and x86_64 interpreters
482 env_list = ["arm64", "x86_64"]
483
484 [env.arm64]
485 base_python = ["cpython3.12-64-arm64"]
486 commands = [["pytest"]]
487
488 [env.x86_64]
489 base_python = ["cpython3.12-64-x86_64"]
490 commands = [["pytest"]]
491
492 .. tab:: INI
493
494 .. code-block:: ini
495
496 [tox]
497 env_list = arm64, x86_64
498
499 [testenv:arm64]
500 base_python = cpython3.12-64-arm64
501 commands = pytest
502
503 [testenv:x86_64]
504 base_python = cpython3.12-64-x86_64
505 commands = pytest
506
507 If the discovered interpreter's architecture does not match the requested one, tox raises a failure — just as it does
508 for Python version mismatches. The matched architecture is recorded in the tox journal under the ``machine`` key.
509
510 Common architecture values (after normalization):
511
512 - ``x86_64`` — 64-bit x86 (Intel/AMD)
513 - ``arm64`` — 64-bit ARM (Apple Silicon, Graviton, Ampere)
514 - ``x86`` — 32-bit x86
515 - ``s390x`` — IBM Z mainframe
516 - ``ppc64le`` — 64-bit PowerPC little-endian
517
518 .. _howto_conditional_values:
519
520 *********************************
521 Set values based on a condition
522 *********************************
523
524 .. versionadded:: 4.40 Conditional value replacement with ``env.VAR`` lookups.
525
526 .. versionchanged:: 4.42 Added ``factor.NAME`` lookups for environment name factors and platform.
527
528 .. versionchanged:: 4.50 Added ``factor['NAME']``/``env['VAR']`` subscript syntax and ``env_name`` variable.
529
530 TOML configurations can conditionally select values based on environment variables and factors using ``replace = "if"``.
531 The ``condition`` field accepts expressions with ``env.VAR`` lookups for environment variables, ``factor.NAME`` lookups
532 for environment name factors and platform, ``==``/``!=`` comparisons, and ``and``/``or``/``not`` boolean logic.
533
534 Set a variable depending on whether you are in CI:
535
536 .. code-block:: toml
537
538 [env_run_base]
539 set_env.MATURITY = { replace = "if", condition = "env.CI", then = "release", "else" = "dev" }
540
541 Add verbose flags to commands when a ``DEBUG`` variable is set:
542
543 .. code-block:: toml
544
545 [env_run_base]
546 commands = [["pytest", { replace = "if", condition = "env.DEBUG", then = ["-vv", "--tb=long"], "else" = [], extend = true }]]
547
548 Use different dependencies based on environment factors:
549
550 .. code-block:: toml
551
552 [env_run_base]
553 deps = [
554 "pytest",
555 { replace = "if", condition = "factor.django50", then = ["Django>=5.0,<5.1"], "else" = ["Django>=4.2,<4.3"], extend = true },
556 ]
557
558 Combine multiple conditions (environment variables and factors):
559
560 .. code-block:: toml
561
562 [env.deploy]
563 commands = [["deploy", { replace = "if", condition = "env.CI and env.TAG_NAME != ''", then = ["--production"], "else" = ["--dry-run"], extend = true }]]
564
565 [env_run_base]
566 commands = [["pytest", { replace = "if", condition = "factor.linux and not env.CI", then = ["--numprocesses=auto"], "else" = [], extend = true }]]
567
568 Use subscript syntax for version-number factors that aren't valid Python identifiers:
569
570 .. code-block:: toml
571
572 [env."test-3.14"]
573 commands = [
574 ["pytest", { replace = "if", condition = "factor['3.14']", then = ["--strict-markers"], "else" = [], extend = true }],
575 ]
576
577 Target a specific environment by name with ``env_name``:
578
579 .. code-block:: toml
580
581 [env_run_base]
582 set_env.EXTRA = { replace = "if", condition = "env_name == 'test-3.14'", then = "latest", "else" = "" }
583
584 For the full expression syntax and more examples, see :ref:`conditional-value-reference`.
585
586 *****************************************
587 Handle env names that match subcommands
588 *****************************************
589
590 tox has built-in subcommands (``run``, ``list``, ``config``, etc.). If you have an environment name that matches a
591 subcommand, use the ``run`` subcommand explicitly:
592
593 .. code-block:: bash
594
595 # This would be interpreted as "tox list", not "run the list environment"
596 # tox -e list # does NOT work as expected
597
598 # Use the run subcommand explicitly
599 tox run -e list
600
601 # Or the short alias
602 tox r -e list
603
604 .. ------------------------------------------------------------------------------------------
605
606 .. Dependencies & Packages
607
608 .. ------------------------------------------------------------------------------------------
609
610 .. _howto_pep723:
611
612 **********************
613 Run a PEP 723 script
614 **********************
615
616 .. versionadded:: 4.52
617
618 If you have a standalone Python script with :PEP:`723` inline metadata:
619
620 .. code-block:: python
621
622 # /// script
623 # requires-python = ">=3.12"
624 # dependencies = ["requests>=2.31", "rich"]
625 # ///
626
627 import requests
628 from rich import print
629
630 print(requests.get("https://httpbin.org/get").json())
631
632 You can run it through tox without duplicating the dependency list:
633
634 .. tab:: TOML
635
636 .. code-block:: toml
637
638 [env.fetch]
639 runner = "virtualenv-pep-723"
640 script = "tools/fetch.py"
641
642 .. tab:: INI
643
644 .. code-block:: ini
645
646 [testenv:fetch]
647 runner = virtualenv-pep-723
648 script = tools/fetch.py
649
650 Run it with ``tox r -e fetch``. Positional arguments are forwarded: ``tox r -e fetch -- --verbose``.
651
652 To override the default command (which runs the script), set ``commands`` as usual:
653
654 .. tab:: TOML
655
656 .. code-block:: toml
657
658 [env.fetch]
659 runner = "virtualenv-pep-723"
660 script = "tools/fetch.py"
661 commands = [["python", "-m", "pytest", "tests/"]]
662
663 .. tab:: INI
664
665 .. code-block:: ini
666
667 [testenv:fetch]
668 runner = virtualenv-pep-723
669 script = tools/fetch.py
670 commands = python -m pytest tests/
671
672 See :ref:`pep723-explanation` for how Python version resolution and dependency installation work.
673
674 .. _faq_custom_pypi_server:
675
676 .. _howto_custom_pypi_server:
677
678 **************************
679 Use a custom PyPI server
680 **************************
681
682 By default tox uses pip to install Python dependencies. To change the index server, configure pip directly via
683 environment variables:
684
685 .. tab:: TOML
686
687 .. code-block:: toml
688
689 [env_run_base]
690 set_env = { PIP_INDEX_URL = "https://my.pypi.example/simple" }
691
692 To allow the user to override the index server (e.g. for offline use), use substitution with a default:
693
694 .. code-block:: toml
695
696 [env_run_base]
697 set_env = { PIP_INDEX_URL = { replace = "env", name = "PIP_INDEX_URL", default = "https://my.pypi.example/simple" } }
698
699 .. tab:: INI
700
701 .. code-block:: ini
702
703 [testenv]
704 set_env =
705 PIP_INDEX_URL = https://my.pypi.example/simple
706
707 To allow the user to override the index server (e.g. for offline use), use substitution with a default:
708
709 .. code-block:: ini
710
711 [testenv]
712 set_env =
713 PIP_INDEX_URL = {env:PIP_INDEX_URL:https://my.pypi.example/simple}
714
715 ***************************
716 Use multiple PyPI servers
717 ***************************
718
719 When not all dependencies are found on a single index, use ``PIP_EXTRA_INDEX_URL``:
720
721 .. tab:: TOML
722
723 .. code-block:: toml
724
725 [env_run_base]
726 set_env.PIP_INDEX_URL = { replace = "env", name = "PIP_INDEX_URL", default = "https://primary.example/simple" }
727 set_env.PIP_EXTRA_INDEX_URL = { replace = "env", name = "PIP_EXTRA_INDEX_URL", default = "https://secondary.example/simple" }
728
729 .. tab:: INI
730
731 .. code-block:: ini
732
733 [testenv]
734 set_env =
735 PIP_INDEX_URL = {env:PIP_INDEX_URL:https://primary.example/simple}
736 PIP_EXTRA_INDEX_URL = {env:PIP_EXTRA_INDEX_URL:https://secondary.example/simple}
737
738 If the index defined under ``PIP_INDEX_URL`` does not contain a package, pip will attempt to resolve it from
739 ``PIP_EXTRA_INDEX_URL``.
740
741 .. warning::
742
743 Using an extra PyPI index for installing private packages may cause security issues. If ``package1`` is registered
744 with the default PyPI index, pip will install ``package1`` from the default PyPI index, not from the extra one.
745
746 **********************
747 Use constraint files
748 **********************
749
750 `Constraint files <https://pip.pypa.io/en/stable/user_guide/#constraints-files>`_ define version constraints for
751 dependencies without specifying what to install. When creating a test environment, tox invokes pip multiple times:
752
753 1. If :ref:`deps` is specified, it installs those dependencies first.
754 2. If the environment has a package (not :ref:`package` ``skip`` or :ref:`skip_install` ``true``), it:
755
756 1. Installs the package dependencies.
757 2. Installs the package itself.
758
759 When ``constrain_package_deps = true`` is set, ``{env_dir}/constraints.txt`` is generated during ``install_deps`` based
760 on the specifications in ``deps``. These constraints are then passed to pip during ``install_package_deps``, raising an
761 error when package dependencies conflict with test dependencies.
762
763 For stronger guarantees, set ``use_frozen_constraints = true`` to generate constraints from the exact installed versions
764 (via ``pip freeze``). This catches incompatibilities with any previously installed dependency.
765
766 .. note::
767
768 Constraint files are a subset of requirement files. You can pass a constraint file wherever a requirement file is
769 accepted.
770
771 ************
772 Use extras
773 ************
774
775 If your package defines optional dependency groups (extras) in ``pyproject.toml``, you can install them in tox
776 environments via the :ref:`extras` configuration:
777
778 .. tab:: TOML
779
780 .. code-block:: toml
781
782 # pyproject.toml
783 [project.optional-dependencies]
784 testing = ["pytest>=8", "coverage"]
785 docs = ["sphinx>=7"]
786
787 .. code-block:: toml
788
789 # tox.toml
790 [env_run_base]
791 extras = ["testing"]
792
793 [env.docs]
794 extras = ["docs"]
795 commands = [["sphinx-build", "-W", "docs", "docs/_build/html"]]
796
797 .. tab:: INI
798
799 .. code-block:: ini
800
801 [testenv]
802 extras = testing
803
804 [testenv:docs]
805 extras = docs
806 commands = sphinx-build -W docs docs/_build/html
807
808 This installs your package together with the specified extras, avoiding the need to duplicate dependency lists in both
809 ``pyproject.toml`` and your tox configuration.
810
811 ************************************
812 Install extras without the package
813 ************************************
814
815 Sometimes you need the package's dependencies (including extras) without installing the package itself. For example,
816 coverage combining, documentation builds, or linting environments that share the same dependency set. Use ``package =
817 "deps-only"`` instead of ``skip_install = true`` combined with manually duplicated ``deps``:
818
819 .. tab:: TOML
820
821 .. code-block:: toml
822
823 # pyproject.toml
824 [project]
825 name = "myproject"
826 dependencies = ["httpx>=0.27"]
827
828 [project.optional-dependencies]
829 docs = ["sphinx>=7", "furo"]
830
831 .. code-block:: toml
832
833 # tox.toml
834 [env.docs]
835 package = "deps-only"
836 extras = ["docs"]
837 commands = [["sphinx-build", "-W", "docs", "docs/_build/html"]]
838
839 .. tab:: INI
840
841 .. code-block:: ini
842
843 [testenv:docs]
844 package = deps-only
845 extras = docs
846 commands = sphinx-build -W docs docs/_build/html
847
848 This reads your ``pyproject.toml`` directly (no build step) and installs ``httpx``, ``sphinx``, and ``furo`` into the
849 environment. If your dependencies are dynamic, tox falls back to using the packaging environment to extract metadata.
850
851 **********************************************
852 Install locked dependencies from pylock.toml
853 **********************************************
854
855 If your project maintains :PEP:`751` lock files (``pylock.toml``), you can install those locked dependencies directly
856 via the :ref:`pylock` configuration. The :ref:`pylock` setting is mutually exclusive with :ref:`deps` — use one or the
857 other. Each package in the lock file is installed as a pinned requirement (``name==version``) with ``--no-deps`` (since
858 the lock file already contains all transitive dependencies), and tox automatically recreates the environment when the
859 lock file changes.
860
861 .. tab:: TOML
862
863 .. code-block:: toml
864
865 # tox.toml
866 [env_run_base]
867 pylock = "pylock.toml"
868
869 .. tab:: INI
870
871 .. code-block:: ini
872
873 [testenv]
874 pylock = pylock.toml
875
876 The locked dependencies are installed first, then the project itself is built and installed normally (unless
877 ``skip_install`` or ``package = "skip"`` is set). When the lock file contains :PEP:`751` extras or dependency groups,
878 use the existing :ref:`extras` and :ref:`dependency_groups` settings to select which ones to include. Packages with
879 markers like ``'docs' in extras`` or ``'dev' in dependency_groups`` are filtered at install time — only packages
880 matching the selected extras/groups (and the target Python's platform markers) are installed:
881
882 .. tab:: TOML
883
884 .. code-block:: toml
885
886 [env.docs]
887 pylock = "pylock.toml"
888 extras = ["docs"]
889
890 [env.dev]
891 pylock = "pylock.toml"
892 dependency_groups = ["dev"]
893
894 .. tab:: INI
895
896 .. code-block:: ini
897
898 [testenv:docs]
899 pylock = pylock.toml
900 extras = docs
901
902 [testenv:dev]
903 pylock = pylock.toml
904 dependency_groups = dev
905
906 .. ------------------------------------------------------------------------------------------
907
908 .. Environment Customization
909
910 .. ------------------------------------------------------------------------------------------
911
912 *******************************
913 Customize virtualenv creation
914 *******************************
915
916 tox uses :pypi:`virtualenv` to create Python virtual environments. Customize virtualenv behavior through environment
917 variables:
918
919 .. tab:: TOML
920
921 .. code-block:: toml
922
923 [env_run_base]
924 set_env.VIRTUALENV_PIP = "22.1"
925 set_env.VIRTUALENV_SYSTEM_SITE_PACKAGES = "true"
926
927 .. tab:: INI
928
929 .. code-block:: ini
930
931 [testenv]
932 set_env =
933 VIRTUALENV_PIP = 22.1
934 VIRTUALENV_SYSTEM_SITE_PACKAGES = true
935
936 Any CLI flag for virtualenv can be set as an environment variable with the ``VIRTUALENV_`` prefix (in uppercase).
937 Consult the :pypi:`virtualenv` documentation for supported values.
938
939 .. _howto_clean_caches:
940
941 *****************************************
942 Clean external caches during recreation
943 *****************************************
944
945 Tools like :pypi:`pre-commit` maintain their own caches outside the tox environment directory. When you recreate an
946 environment with ``tox run -r``, those external caches are left behind. Use :ref:`recreate_commands` to run cleanup
947 commands inside the old environment before it is removed:
948
949 .. tab:: TOML
950
951 .. code-block:: toml
952
953 [env_run_base]
954 deps = ["pre-commit"]
955 recreate_commands = [["{env_python}", "-Im", "pre_commit", "clean"]]
956 commands = [["pre-commit", "run", "--all-files"]]
957
958 .. tab:: INI
959
960 .. code-block:: ini
961
962 [testenv]
963 deps = pre-commit
964 recreate_commands = {env_python} -Im pre_commit clean
965 commands = pre-commit run --all-files
966
967 These commands only run during recreation -- they are skipped on first creation and on normal re-runs. Failures are
968 logged as warnings and never block the recreation itself.
969
970 *****************************************
971 Test across old and new Python versions
972 *****************************************
973
974 When a project must support both very old (e.g. Python 3.6) and very new (e.g. Python 3.15) interpreters, no single
975 virtualenv release covers both. Use :ref:`virtualenv_spec` to pin a different virtualenv version per environment:
976
977 .. tab:: TOML
978
979 .. code-block:: toml
980
981 env_list = ["3.6", "3.15", "3.13"]
982
983 [env_run_base]
984 deps = ["pytest"]
985 commands = [["pytest"]]
986
987 [env."3.6"]
988 virtualenv_spec = "virtualenv<20.22.0"
989
990 .. tab:: INI
991
992 .. code-block:: ini
993
994 [tox]
995 env_list = 3.6, 3.15, 3.13
996
997 [testenv]
998 deps = pytest
999 commands = pytest
1000
1001 [testenv:3.6]
1002 virtualenv_spec = virtualenv<20.22.0
1003
1004 The ``3.6`` environment uses an older virtualenv that still supports Python 3.6, while other environments use the
1005 default (imported) virtualenv. The first run bootstraps the pinned version; subsequent runs reuse the cached bootstrap.
1006
1007 .. _howto_generate_matrix:
1008
1009 ***************************************
1010 Generate environment matrices in TOML
1011 ***************************************
1012
1013 TOML ``env_list`` composes environments from structured dicts: string literals, bare range dicts (``{ prefix, start,
1014 stop }``), labeled dicts, and ``product`` dicts. TOML never interprets curly braces inside strings — every axis is
1015 expressed as an explicit structured item. For a single axis use the bare range dict:
1016
1017 .. tab:: TOML
1018
1019 .. code-block:: toml
1020
1021 env_list = [
1022 "lint",
1023 { prefix = "3.", start = 12, stop = 14 },
1024 ]
1025
1026 .. tab:: INI
1027
1028 .. code-block:: ini
1029
1030 [tox]
1031 env_list = lint, 3.{12-14}
1032
1033 For multi-dimensional matrices, use a ``product`` dict whose items are arrays of strings or range/labeled dicts.
1034 Combinations are joined with ``-``:
1035
1036 .. tab:: TOML
1037
1038 .. code-block:: toml
1039
1040 env_list = [
1041 "lint",
1042 { product = [
1043 { prefix = "3.", start = 12, stop = 14 },
1044 ["django42", "django50"],
1045 ] },
1046 ]
1047
1048 [env_run_base]
1049 package = "skip"
1050 deps = [
1051 "pytest",
1052 { replace = "if", condition = "factor.django42", then = ["Django>=4.2,<4.3"], extend = true },
1053 { replace = "if", condition = "factor.django50", then = ["Django>=5.0,<5.1"], extend = true },
1054 ]
1055 commands = [["pytest"]]
1056
1057 .. tab:: INI
1058
1059 .. code-block:: ini
1060
1061 [tox]
1062 env_list = py3{12-14}-django{42,50}
1063
1064 [testenv]
1065 package = skip
1066 deps =
1067 pytest
1068 django42: Django>=4.2,<4.3
1069 django50: Django>=5.0,<5.1
1070 commands = pytest
1071
1072 This generates ``lint``, ``py312-django42``, ``py312-django50``, ``py313-django42``, ``py313-django50``,
1073 ``py314-django42``, ``py314-django50``.
1074
1075 To skip incompatible combinations, add ``exclude`` -- this is only available in TOML:
1076
1077 .. code-block:: toml
1078
1079 env_list = [
1080 { product = [["py312", "py313"], ["django42", "django50"]], exclude = ["py312-django50"] },
1081 ]
1082
1083 .. _howto_env_base_matrix:
1084
1085 ***********************************************
1086 Test a matrix of configurations with env_base
1087 ***********************************************
1088
1089 When multiple environments share the same deps, commands, and other settings but differ only by factors, use
1090 ``env_base`` templates instead of repeating configuration across ``[env.X]`` sections. The ``factors`` key defines the
1091 Cartesian product of factor groups, and each generated environment inherits all other settings from the template:
1092
1093 .. code-block:: toml
1094
1095 [env_base.django]
1096 factors = [
1097 { prefix = "py3", start = 13, stop = 14 },
1098 ["django42", "django50"],
1099 ]
1100 package = "skip"
1101 deps = [
1102 "pytest",
1103 { replace = "if", condition = "factor.django42", then = ["Django>=4.2,<4.3"], extend = true },
1104 { replace = "if", condition = "factor.django50", then = ["Django>=5.0,<5.1"], extend = true },
1105 ]
1106 commands = [["pytest"]]
1107
1108 This generates ``django-py313-django42``, ``django-py313-django50``, ``django-py314-django42``,
1109 ``django-py314-django50``. Each environment resolves factor conditions independently -- ``django-py313-django42`` gets
1110 ``Django>=4.2,<4.3`` while ``django-py314-django50`` gets ``Django>=5.0,<5.1``.
1111
1112 To override a specific generated environment, add an explicit ``[env.NAME]`` section:
1113
1114 .. code-block:: toml
1115
1116 [env.django-py314-django50]
1117 description = "bleeding edge"
1118
1119 The inheritance chain is: ``[env.{name}]`` > ``[env_base.{template}]`` > ``[env_run_base]``.
1120
1121 See :ref:`env-base-templates` for the full reference.
1122
1123 ***************************
1124 Ignore command exit codes
1125 ***************************
1126
1127 When multiple commands are defined in :ref:`commands`, tox runs them sequentially and stops at the first failure
1128 (non-zero exit code). To ignore the exit code of a specific command, prefix it with ``-``:
1129
1130 .. tab:: TOML
1131
1132 .. code-block:: toml
1133
1134 [env_run_base]
1135 commands = [
1136 ["-", "python", "-c", "import sys; sys.exit(1)"],
1137 ["python", "--version"],
1138 ]
1139
1140 .. tab:: INI
1141
1142 .. code-block:: ini
1143
1144 [testenv]
1145 commands =
1146 - python -c 'import sys; sys.exit(1)'
1147 python --version
1148
1149 To invert the exit code (fail if the command returns 0, succeed otherwise), use the ``!`` prefix:
1150
1151 .. tab:: TOML
1152
1153 .. code-block:: toml
1154
1155 [env_run_base]
1156 commands = [
1157 ["!", "python", "-c", "import sys; sys.exit(1)"],
1158 ["python", "--version"],
1159 ]
1160
1161 .. tab:: INI
1162
1163 .. code-block:: ini
1164
1165 [testenv]
1166 commands =
1167 ! python -c 'import sys; sys.exit(1)'
1168 python --version
1169
1170 **********************
1171 Retry flaky commands
1172 **********************
1173
1174 Commands that fail due to transient errors (network timeouts, flaky tests) can be automatically retried using
1175 :ref:`commands_retry`. The value specifies how many times to retry a failed command -- a value of ``2`` means each
1176 command is attempted up to 3 times total. Retries apply to :ref:`commands_pre`, :ref:`commands`, and
1177 :ref:`commands_post`. Commands prefixed with ``-`` (ignore exit code) are never retried.
1178
1179 .. tab:: TOML
1180
1181 .. code-block:: toml
1182
1183 [env.integration]
1184 description = "run integration tests with retries for flaky network calls"
1185 commands_retry = 2
1186 commands = [["pytest", "tests/integration"]]
1187
1188 .. tab:: INI
1189
1190 .. code-block:: ini
1191
1192 [testenv:integration]
1193 description = run integration tests with retries for flaky network calls
1194 commands_retry = 2
1195 commands = pytest tests/integration
1196
1197 **********************
1198 Control color output
1199 **********************
1200
1201 tox uses colored output by default. To disable it, use any of these methods:
1202
1203 .. code-block:: bash
1204
1205 # Via environment variable
1206 NO_COLOR=1 tox run
1207
1208 # Via TERM
1209 TERM=dumb tox run
1210
1211 # Via CLI flag
1212 tox run --colored no
1213
1214 .. ------------------------------------------------------------------------------------------
1215
1216 .. CI/CD & Automation
1217
1218 .. ------------------------------------------------------------------------------------------
1219
1220 .. _howto-ci:
1221
1222 ****************************
1223 Use tox in CI/CD pipelines
1224 ****************************
1225
1226 tox works well in continuous integration systems. We recommend installing tox via `uv <https://docs.astral.sh/uv/>`__
1227 for significantly faster setup times. Adding :pypi:`tox-uv` also replaces pip with uv inside tox environments, speeding
1228 up dependency installation.
1229
1230 **GitHub Actions**:
1231
1232 .. code-block:: yaml
1233
1234 # .github/workflows/tests.yml
1235 name: tests
1236 on: [push, pull_request]
1237 jobs:
1238 test:
1239 runs-on: ubuntu-latest
1240 strategy:
1241 matrix:
1242 python-version: ["3.12", "3.13", "3.14"]
1243 steps:
1244 - uses: actions/checkout@v4
1245 - uses: actions/setup-python@v5
1246 with:
1247 python-version: ${{ matrix.python-version }}
1248 - uses: astral-sh/setup-uv@v5
1249 - run: uv tool install tox --with tox-uv
1250 - run: tox run -e ${{ matrix.python-version }}
1251
1252 **GitLab CI**:
1253
1254 .. code-block:: yaml
1255
1256 # .gitlab-ci.yml
1257 test:
1258 image: python:3.13
1259 before_script:
1260 - curl -LsSf https://astral.sh/uv/install.sh | sh
1261 - uv tool install tox --with tox-uv
1262 script:
1263 - tox run -e 3.13
1264
1265 .. _howto-docker:
1266
1267 ***********************************
1268 Run tox inside a Docker container
1269 ***********************************
1270
1271 Build a lightweight Docker image that contains tox and your target Python versions. Using `uv
1272 <https://docs.astral.sh/uv/>`__ keeps the image small and installation fast:
1273
1274 .. code-block:: Dockerfile
1275
1276 FROM python:3.13-slim
1277
1278 # Install build tools commonly needed by C-extension packages
1279 RUN set -eux; \
1280 apt-get update; \
1281 apt-get install -y --no-install-recommends gcc make; \
1282 rm -rf /var/lib/apt/lists/*
1283
1284 # Install tox (with tox-uv for faster dependency resolution)
1285 COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
1286 RUN uv tool install tox --with tox-uv
1287
1288 ENV PATH="/root/.local/bin:$PATH"
1289 WORKDIR /app
1290
1291 Mount your project directory and run tox:
1292
1293 .. code-block:: shell
1294
1295 docker build -t tox-runner .
1296 docker run --rm -v "$(pwd)":/app tox-runner tox run -e 3.13
1297
1298 To test against multiple Python versions in the same image, start from a base image and add the versions you need:
1299
1300 .. code-block:: Dockerfile
1301
1302 FROM python:3.13-slim
1303
1304 RUN set -eux; \
1305 apt-get update; \
1306 apt-get install -y --no-install-recommends gcc make; \
1307 rm -rf /var/lib/apt/lists/*
1308
1309 COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
1310
1311 # Install additional Python versions via uv
1312 RUN uv python install 3.12 3.11
1313
1314 RUN uv tool install tox --with tox-uv
1315 ENV PATH="/root/.local/bin:$PATH"
1316 WORKDIR /app
1317
1318 .. code-block:: shell
1319
1320 docker run --rm -v "$(pwd)":/app tox-runner tox run -e 3.13,3.12,3.11
1321
1322 .. note::
1323
1324 The previously recommended `31z4/tox <https://hub.docker.com/r/31z4/tox>`_ Docker image has been `archived
1325 <https://github.com/31z4/tox-docker>`_ and is no longer maintained. The image is still available on Docker Hub but
1326 may not receive updates. Building your own image as shown above is the recommended approach.
1327
1328 .. ------------------------------------------------------------------------------------------
1329
1330 .. Documentation
1331
1332 .. ------------------------------------------------------------------------------------------
1333
1334 *********************************
1335 Build documentation with Sphinx
1336 *********************************
1337
1338 Orchestrate Sphinx documentation builds with tox to integrate them into CI:
1339
1340 .. tab:: TOML
1341
1342 .. code-block:: toml
1343
1344 [env.docs]
1345 description = "build documentation"
1346 deps = ["sphinx>=7"]
1347 commands = [
1348 ["sphinx-build", "-d", "{env_tmp_dir}/doctree", "docs", "{work_dir}/docs_out", "--color", "-b", "html"],
1349 ["python", "-c", "print(f'documentation available under file://{work_dir}/docs_out/index.html')"],
1350 ]
1351
1352 .. tab:: INI
1353
1354 .. code-block:: ini
1355
1356 [testenv:docs]
1357 description = build documentation
1358 deps =
1359 sphinx>=7
1360 commands =
1361 sphinx-build -d "{envtmpdir}{/}doctree" docs "{toxworkdir}{/}docs_out" --color -b html
1362 python -c 'print(r"documentation available under file://{toxworkdir}{/}docs_out{/}index.html")'
1363
1364 This approach avoids the platform-specific Makefile generated by Sphinx and works cross-platform.
1365
1366 *********************************
1367 Build documentation with mkdocs
1368 *********************************
1369
1370 Define separate environments for developing and deploying mkdocs documentation:
1371
1372 .. tab:: TOML
1373
1374 .. code-block:: toml
1375
1376 [env.docs]
1377 description = "run a development server for documentation"
1378 deps = [
1379 "mkdocs>=1.3",
1380 "mkdocs-material",
1381 ]
1382 commands = [
1383 ["mkdocs", "build", "--clean"],
1384 ["python", "-c", "print('###### Starting local server. Press Control+C to stop ######')"],
1385 ["mkdocs", "serve", "-a", "localhost:8080"],
1386 ]
1387
1388 [env.docs-deploy]
1389 description = "build and deploy documentation"
1390 deps = [
1391 "mkdocs>=1.3",
1392 "mkdocs-material",
1393 ]
1394 commands = [["mkdocs", "gh-deploy", "--clean"]]
1395
1396 .. tab:: INI
1397
1398 .. code-block:: ini
1399
1400 [testenv:docs]
1401 description = Run a development server for working on documentation
1402 deps =
1403 mkdocs>=1.3
1404 mkdocs-material
1405 commands =
1406 mkdocs build --clean
1407 python -c 'print("###### Starting local server. Press Control+C to stop server ######")'
1408 mkdocs serve -a localhost:8080
1409
1410 [testenv:docs-deploy]
1411 description = built fresh docs and deploy them
1412 deps = {[testenv:docs]deps}
1413 commands = mkdocs gh-deploy --clean
1414
1415 .. ------------------------------------------------------------------------------------------
1416
1417 .. Troubleshooting & Debugging
1418
1419 .. ------------------------------------------------------------------------------------------
1420
1421 *********************************
1422 Debug a failing tox environment
1423 *********************************
1424
1425 When an environment fails, use these techniques to investigate:
1426
1427 1. **Increase verbosity** to see detailed command output:
1428
1429 .. code-block:: bash
1430
1431 tox run -e 3.13 -vv
1432
1433 2. **Inspect resolved configuration** to verify settings are what you expect:
1434
1435 .. code-block:: bash
1436
1437 # Show all configuration for an environment
1438 tox config -e 3.13
1439
1440 # Show specific keys
1441 tox config -e 3.13 -k deps commands pass_env set_env
1442
1443 3. **Check log files** in ``.tox/<env_name>/log/`` for full command output with timestamps.
1444 4. **Run a command interactively** inside the environment:
1445
1446 .. code-block:: bash
1447
1448 tox exec -e 3.13 -- python
1449 tox exec -e 3.13 -- pip list
1450
1451 5. **Force recreation** if you suspect a stale environment:
1452
1453 .. code-block:: bash
1454
1455 tox run -e 3.13 -r
1456
1457 6. **Check for misplaced config keys**. Options in the wrong section are silently ignored. Use ``-v`` to surface
1458 warnings about unrecognized keys, or run ``tox config`` to see ``# !!! unused:`` markers:
1459
1460 .. code-block:: bash
1461
1462 tox run -v
1463 tox config -e 3.13
1464
1465 7. **Extract configuration in different formats.** Use ``--format`` to choose between ``ini`` (default), ``json``, or
1466 ``toml``. Write to a file with ``-o`` instead of stdout:
1467
1468 .. code-block:: bash
1469
1470 tox config -e py -k deps commands # INI (default)
1471 tox config -e py -k deps commands --format json # JSON to stdout
1472 tox config -e py -k deps commands --format toml -o out.toml # TOML to file
1473
1474 Given a ``tox.ini`` with ``deps = pytest`` and ``commands = pytest {posargs}``, the output looks like:
1475
1476 .. tab:: INI
1477
1478 .. code-block:: ini
1479
1480 [testenv:py]
1481 deps = pytest
1482 commands = pytest
1483
1484 .. tab:: JSON
1485
1486 .. code-block:: json
1487
1488 {
1489 "env": {
1490 "py": {
1491 "deps": [
1492 "pytest"
1493 ],
1494 "commands": [
1495 "pytest"
1496 ]
1497 }
1498 }
1499 }
1500
1501 .. tab:: TOML
1502
1503 .. code-block:: toml
1504
1505 [env.py]
1506 deps = ["pytest"]
1507 commands = ["pytest"]
1508
1509 The JSON and TOML formats preserve native types (booleans, integers, floats, arrays, dicts) and use the same key
1510 structure as ``tox.toml`` (``env.<name>`` for environments, ``tox`` for core settings). The ``-o`` flag always writes
1511 without color codes.
1512
1513 To get the list of environments programmatically, query ``-k type`` — the ``env`` keys in the output are the
1514 environment names:
1515
1516 .. code-block:: bash
1517
1518 tox config -k type --format json | python -c "import json,sys; print(*json.load(sys.stdin)['env'])"
1519
1520 .. _skip-env-install:
1521
1522 **************************************
1523 Reuse an environment without network
1524 **************************************
1525
1526 When working offline, on a plane, or in an air-gapped CI environment, tox still attempts to install dependencies and the
1527 project package on every run. If the environment was previously set up and nothing has changed, you can skip all
1528 installation steps with ``--skip-env-install``:
1529
1530 .. code-block:: bash
1531
1532 # First run: installs everything normally
1533 tox run -e 3.13
1534
1535 # Subsequent runs: skip all installation, reuse existing environment
1536 tox run -e 3.13 --skip-env-install
1537
1538 This skips:
1539
1540 - Installing ``deps`` and dependency groups
1541 - Building and installing the project package
1542
1543 The environment must already exist from a previous run. Commands (``commands_pre``, ``commands``, ``commands_post``)
1544 still execute normally.
1545
1546 ``--skip-env-install`` differs from ``--skip-pkg-install`` in scope: ``--skip-pkg-install`` only skips the package build
1547 and install step, while ``--skip-env-install`` additionally skips dependency installation. Use ``--skip-pkg-install``
1548 when you want to refresh dependencies but not rebuild the package. Use ``--skip-env-install`` when you want to skip all
1549 installation entirely.
1550
1551 .. code-block:: bash
1552
1553 # Skip only package build/install, still install deps
1554 tox run -e 3.13 --skip-pkg-install
1555
1556 # Skip everything: deps + package
1557 tox run -e 3.13 --skip-env-install
1558
1559 .. _run-interactive-programs:
1560
1561 **************************
1562 Run interactive programs
1563 **************************
1564
1565 Interactive programs like Python REPL, debuggers, or TUI applications need direct terminal access to handle user input
1566 and query console properties. By default, tox pipes stdout/stderr to capture output for logging, which breaks terminal
1567 APIs that require real console handles.
1568
1569 Use ``--no-capture`` (or ``-i``) to disable output capture and give the subprocess direct access to the terminal:
1570
1571 .. code-block:: bash
1572
1573 # Open a Python REPL with full terminal support
1574 tox run -e 3.13 -i -- python
1575
1576 # Run a debugger interactively
1577 tox run -e 3.13 -i -- python -m pdb script.py
1578
1579 # Use a TUI application
1580 tox run -e 3.13 -i -- pytest --pdb
1581
1582 The ``--no-capture`` flag is mutually exclusive with ``--result-json`` (which requires output capture) and parallel mode
1583 (where multiple environments' output would interleave). When enabled, tox cannot log command output to
1584 ``.tox/<env_name>/log/`` files.
1585
1586 .. note::
1587
1588 ``tox exec`` always runs in interactive mode without output capture. Use ``tox exec`` for one-off commands that
1589 don't need the full environment setup (see :ref:`tox-exec`). Use ``tox run --no-capture`` when you need to run the
1590 configured commands interactively.
1591
1592 ******************
1593 Access full logs
1594 ******************
1595
1596 tox logs command invocations inside ``.tox/<env_name>/log``. Each execution is recorded in a file named
1597 ``<index>-<run_name>.log``, containing the command, environment variables, working directory, exit code, and output.
1598
1599 Environment variables with names containing sensitive words (``access``, ``api``, ``auth``, ``client``, ``cred``,
1600 ``key``, ``passwd``, ``password``, ``private``, ``pwd``, ``secret``, ``token``) are logged with their values redacted to
1601 prevent accidental secret leaking.
1602
1603 ***************************************
1604 Understand InvocationError exit codes
1605 ***************************************
1606
1607 When a command executed by tox fails, an ``InvocationError`` is raised:
1608
1609 .. code-block:: shell
1610
1611 ERROR: InvocationError for command
1612 '<command defined in tox config>' (exited with code 1)
1613
1614 Always check the documentation for the command that failed. For example, for :pypi:`pytest`, see the `pytest exit codes
1615 <https://docs.pytest.org/en/latest/reference/exit-codes.html#exit-codes>`_.
1616
1617 On Unix systems, exit codes larger than 128 indicate a fatal signal. tox provides a hint in these cases:
1618
1619 .. code-block:: shell
1620
1621 ERROR: InvocationError for command
1622 '<command>' (exited with code 139)
1623 Note: this might indicate a fatal error signal (139 - 128 = 11: SIGSEGV)
1624
1625 Signal numbers are documented in the `signal man page <https://man7.org/linux/man-pages/man7/signal.7.html>`_.
1626
1627 .. ------------------------------------------------------------------------------------------
1628
1629 .. Advanced & Specialized (niche topics at end)
1630
1631 .. ------------------------------------------------------------------------------------------
1632
1633 .. _pin-default-python:
1634
1635 ******************************
1636 Pin a default Python version
1637 ******************************
1638
1639 When environments like ``lint`` or ``type`` don't contain a Python factor, tox uses the Python it's installed into. This
1640 varies across machines -- a contributor on Ubuntu 22.04 gets Python 3.10, while Fedora 37 gives 3.11 -- leading to
1641 unreproducible results or failures when dependencies don't support the host's Python version.
1642
1643 Set :ref:`default_base_python` to pin a fallback interpreter for all environments without a Python factor:
1644
1645 .. tab:: TOML
1646
1647 .. code-block:: toml
1648
1649 [env_run_base]
1650 default_base_python = ["3.14", "3.13"]
1651
1652 .. tab:: INI
1653
1654 .. code-block:: ini
1655
1656 [testenv]
1657 default_base_python = 3.14, 3.13
1658
1659 Environments with a Python factor (e.g. ``3.13``, ``py313``) or an explicit :ref:`base_python` setting are unaffected.
1660
1661 .. ------------------------------------------------------------------------------------------
1662
1663 .. _open-ended-ranges:
1664
1665 **********************************************
1666 Future-proof env_list with open-ended ranges
1667 **********************************************
1668
1669 Instead of updating ``env_list`` every time a new Python version is released, use open-ended ranges:
1670
1671 .. tab:: TOML
1672
1673 .. code-block:: toml
1674
1675 env_list = [
1676 { prefix = "3.", start = 10 },
1677 "lint",
1678 ]
1679
1680 .. tab:: INI
1681
1682 .. code-block:: ini
1683
1684 [tox]
1685 env_list = 3.{10-}, lint
1686
1687 This expands up to the latest `supported CPython version <https://devguide.python.org/versions/>`_ known to tox. When
1688 you upgrade tox after a new Python release, the range automatically includes the new version. The bare range dict is the
1689 single-axis spelling; wrap it in ``{ product = [...] }`` only when crossing it with another factor group.
1690
1691 To start from the oldest supported version:
1692
1693 .. tab:: TOML
1694
1695 .. code-block:: toml
1696
1697 env_list = [
1698 { prefix = "3.", stop = 13 },
1699 "lint",
1700 ]
1701
1702 .. tab:: INI
1703
1704 .. code-block:: ini
1705
1706 [tox]
1707 env_list = 3.{-13}, lint
1708
1709 This expands down from the oldest supported CPython version. Both forms can be mixed with explicit values:
1710
1711 .. tab:: TOML
1712
1713 .. code-block:: toml
1714
1715 env_list = [
1716 { prefix = "3.", start = 10 },
1717 "3.8",
1718 "lint",
1719 ]
1720
1721 .. tab:: INI
1722
1723 .. code-block:: ini
1724
1725 [tox]
1726 env_list = 3.{10-, 8}, lint
1727
1728 See :ref:`generative-environment-list` for the full range syntax reference.
1729
1730 .. ------------------------------------------------------------------------------------------
1731
1732 .. _eol-version-support:
1733
1734 **********************************
1735 Test end-of-life Python versions
1736 **********************************
1737
1738 tox uses :pypi:`virtualenv` under the hood. Newer virtualenv versions drop support for older Python interpreters:
1739
1740 - `virtualenv 20.22.0 <https://virtualenv.pypa.io/en/latest/changelog.html#v20-22-0-2023-04-19>`_ dropped Python 3.6 and
1741 earlier
1742 - `virtualenv 20.27.0 <https://virtualenv.pypa.io/en/latest/changelog.html#v20-27-0-2024-10-17>`_ dropped Python 3.7
1743
1744 To test against these versions, pin virtualenv:
1745
1746 .. tab:: TOML
1747
1748 .. code-block:: toml
1749
1750 requires = ["virtualenv<20.22.0"]
1751
1752 .. tab:: INI
1753
1754 .. code-block:: ini
1755
1756 [tox]
1757 requires = virtualenv<20.22.0
1758
1759 ***************************************
1760 Use tox with different build backends
1761 ***************************************
1762
1763 tox works with any :PEP:`517`/:PEP:`518` compliant build backend. Configure the backend in ``pyproject.toml``:
1764
1765 **Hatchling** (``hatch``):
1766
1767 .. code-block:: toml
1768
1769 [build-system]
1770 requires = ["hatchling"]
1771 build-backend = "hatchling.build"
1772
1773 **Flit**:
1774
1775 .. code-block:: toml
1776
1777 [build-system]
1778 requires = ["flit_core>=3.4"]
1779 build-backend = "flit_core.buildapi"
1780
1781 **PDM**:
1782
1783 .. code-block:: toml
1784
1785 [build-system]
1786 requires = ["pdm-backend"]
1787 build-backend = "pdm.backend"
1788
1789 tox automatically detects and uses whatever backend is specified in ``[build-system]``. No additional tox configuration
1790 is needed. For build backends that need extra configuration during the build, use :ref:`config_settings_build_wheel` and
1791 related options.
1792
1793 .. _howto-reference-built-package:
1794
1795 **********************************************
1796 Reference the built package path in commands
1797 **********************************************
1798
1799 When tox builds an sdist or wheel for your project it stores the path in the ``TOX_PACKAGE`` environment variable (see
1800 :ref:`injected-environment-variables`). Reference it in ``commands`` (or any other config value) to run post-build
1801 checks such as ``twine check``, ``check-wheel-contents``, or ``pkginfo`` against the exact artifact that was just built
1802 and installed.
1803
1804 .. tab:: TOML
1805
1806 Use the explicit environment variable reference (see :ref:`pyproject-toml-native`):
1807
1808 .. code-block:: toml
1809
1810 [env.check]
1811 description = "check the built package"
1812 deps = ["twine"]
1813 commands = [["twine", "check", { replace = "env", name = "TOX_PACKAGE" }]]
1814
1815 .. tab:: INI
1816
1817 .. code-block:: ini
1818
1819 [testenv:check]
1820 description = check the built package
1821 deps = twine
1822 commands = twine check {env:TOX_PACKAGE}
1823
1824 ``TOX_PACKAGE`` is only set in run environments where a package has been built. If there are multiple artifacts (for
1825 example both an sdist and a wheel), the paths are joined with ``os.pathsep``.
1826
1827 .. tip::
1828
1829 If you need a glob-based approach instead (e.g. matching files produced outside of tox), use the ``{glob:PATTERN}``
1830 substitution — see :ref:`substitution-reference`.
1831
1832 **********************************
1833 Migrate from tox.ini to tox.toml
1834 **********************************
1835
1836 TOML is the recommended configuration format for new projects. Here is how common INI patterns translate to TOML:
1837
1838 **Basic structure**:
1839
1840 .. tab:: TOML
1841
1842 .. code-block:: toml
1843
1844 # tox.toml - values at root level are core settings
1845 requires = ["tox>=4.20"]
1846 env_list = ["3.13", "3.12", "lint"]
1847
1848 # base settings for run environments
1849 [env_run_base]
1850 deps = ["pytest>=8"]
1851 commands = [["pytest", "tests"]]
1852
1853 # environment-specific overrides
1854 [env.lint]
1855 skip_install = true
1856 deps = ["ruff"]
1857 commands = [["ruff", "check", "."]]
1858
1859 .. tab:: INI
1860
1861 .. code-block:: ini
1862
1863 [tox]
1864 requires = tox>=4.20
1865 env_list = 3.13, 3.12, lint
1866
1867 [testenv]
1868 deps = pytest>=8
1869 commands = pytest tests
1870
1871 [testenv:lint]
1872 skip_install = true
1873 deps = ruff
1874 commands = ruff check .
1875
1876 **Key differences**:
1877
1878 - Strings must be quoted in TOML: ``description = "run tests"`` vs ``description = run tests``
1879 - Lists use JSON syntax: ``deps = ["pytest", "ruff"]`` vs multi-line ``deps = \n pytest \n ruff``
1880 - Commands are list-of-lists: ``commands = [["pytest", "tests"]]`` vs ``commands = pytest tests``
1881 - Positional arguments use replacement objects: ``{ replace = "posargs", default = ["tests"] }`` vs ``{posargs:tests}``
1882 - Environment variables in ``set_env`` use ``{ replace = "env", name = "VAR" }`` vs ``{env:VAR}``
1883 - Section references use ``{ replace = "ref", ... }`` vs ``{[section]key}``
1884 - Factor conditions use ``{ replace = "if", condition = "factor.NAME", ... }`` vs ``NAME:``
1885 - Generative environment lists use structured dicts (bare ``{ prefix, start, stop }`` for a single axis, ``{ product =
1886 [...] }`` for matrices) vs ``{a,b}-{c,d}`` brace expansion
1887
1888 *************************************
1889 Format your tox configuration files
1890 *************************************
1891
1892 Consistent formatting makes configuration files easier to read and review. The tox-dev organization maintains
1893 opinionated formatters for both TOML and INI configurations, available as pre-commit hooks or standalone CLI tools.
1894
1895 .. tab:: TOML
1896
1897 Use :pypi:`tox-toml-fmt` for ``tox.toml`` or TOML-based configuration in ``pyproject.toml``. It standardizes
1898 quoting, array formatting, and table organization:
1899
1900 .. code-block:: yaml
1901
1902 # .pre-commit-config.yaml
1903 - repo: https://github.com/tox-dev/toml-fmt
1904 rev: "1.6.0"
1905 hooks:
1906 - id: tox-toml-fmt
1907
1908 Also available as a standalone command via ``pipx install tox-toml-fmt``.
1909
1910 .. tab:: INI
1911
1912 Use :pypi:`tox-ini-fmt` for ``tox.ini`` files. It normalizes boolean fields, orders sections consistently, and
1913 formats multi-line values with uniform indentation:
1914
1915 .. code-block:: yaml
1916
1917 # .pre-commit-config.yaml
1918 - repo: https://github.com/tox-dev/tox-ini-fmt
1919 rev: "1.7.1"
1920 hooks:
1921 - id: tox-ini-fmt
1922
1923 Also available as a standalone command via ``pipx install tox-ini-fmt``.