Debian Codegraph @

docs/reference/config.rst

raw
1 .. _configuration:
2
3 ###############
4 Configuration
5 ###############
6
7 tox configuration can be split into two categories: core and environment specific. Core settings are options that can be
8 set once and used for all tox environments, while environment options are applied to the given tox environment only.
9
10 .. _compatibility-requirements:
11
12 *********************
13 System requirements
14 *********************
15
16 tox works with the following Python interpreter implementations:
17
18 - `CPython <https://www.python.org/>`_ versions 3.10, 3.11, 3.12, 3.13, 3.14
19
20 This means tox works on the latest patch version of each of these minor versions. Previous patch versions are supported
21 on a best effort approach.
22
23 **************************
24 Discovery and file types
25 **************************
26
27 With regards to the configuration format, at the moment we support the following formats:
28
29 - `INI <https://en.wikipedia.org/wiki/INI_file>`_.
30 - `TOML <https://toml.io/en/v1.0.0>`_.
31
32 Out of box tox supports five configuration locations prioritized in the following order:
33
34 .. mermaid::
35
36 flowchart TD
37 search[tox searches current directory] --> tox_ini
38 tox_ini[tox.ini — INI] -- not found --> setup_cfg[setup.cfg — INI]
39 setup_cfg -- not found --> pyproject_native[pyproject.toml — tool.tox]
40 pyproject_native -- not found --> pyproject_legacy[pyproject.toml — legacy_tox_ini]
41 pyproject_legacy -- not found --> tox_toml[tox.toml — TOML]
42
43 classDef ini fill:#dbeafe,stroke:#3b82f6,stroke-width:2px,color:#1e3a5f
44 classDef toml fill:#dcfce7,stroke:#22c55e,stroke-width:2px,color:#14532d
45 classDef start fill:#f3f4f6,stroke:#9ca3af,stroke-width:2px,color:#374151
46
47 class tox_ini,setup_cfg,pyproject_legacy ini
48 class pyproject_native,tox_toml toml
49 class search start
50
51 1. ``tox.ini`` (INI),
52 2. ``setup.cfg`` (INI),
53 3. Native ``pyproject.toml`` under the ``tool.tox`` table (TOML),
54 4. ``pyproject.toml`` with the ``tool.tox`` table, having ``legacy_tox_ini`` key (containing INI),
55 5. ``tox.toml`` (TOML).
56
57 Historically, the INI format was created first, and TOML was added in 2024. **TOML is the recommended format for new
58 projects** -- it is more robust, has proper type support, and avoids ambiguities inherent in INI parsing (e.g.
59 multi-line values, comment escaping). INI remains supported and is more concise for some patterns.
60
61 .. _toml-feature-gaps:
62
63 Format comparison
64 =================
65
66 Both INI and TOML support the same features with different syntax. The only INI feature without a TOML equivalent is
67 generative section names (see below).
68
69 **Conditional factors** -- Both INI and TOML support filtering by factor name. A factor is any dash-separated segment in
70 the environment name (e.g. ``py313-django50`` has factors ``py313`` and ``django50``). Additionally, the current
71 platform (``sys.platform`` value like ``linux``, ``darwin``, ``win32``) is automatically available as an implicit
72 factor.
73
74 .. tab:: TOML
75
76 .. code-block:: toml
77
78 [env_run_base]
79 deps = [
80 "pytest",
81 { replace = "if", condition = "factor.django50", then = ["Django>=5.0,<5.1"], extend = true },
82 { replace = "if", condition = "factor.django42", then = ["Django>=4.2,<4.3"], extend = true },
83 { replace = "if", condition = "not factor.lint", then = ["coverage"], extend = true },
84 ]
85 commands = [
86 { replace = "if", condition = "factor.linux", then = [["python", "-c", "print('on linux')"]], extend = true },
87 { replace = "if", condition = "factor.darwin", then = [["python", "-c", "print('on mac')"]], extend = true },
88 { replace = "if", condition = "factor.win32", then = [["python", "-c", "print('on windows')"]], extend = true },
89 ]
90
91 Use ``replace = "if"`` with ``factor.NAME`` conditions. Supports boolean operations (``and``, ``or``, ``not``) and
92 can combine with environment variable checks (``env.VAR``).
93
94 .. tab:: INI
95
96 .. code-block:: ini
97
98 [testenv]
99 deps =
100 pytest
101 django50: Django>=5.0,<5.1
102 django42: Django>=4.2,<4.3
103 !lint: coverage
104 commands =
105 linux: python -c 'print("on linux")'
106 darwin: python -c 'print("on mac")'
107 win32: python -c 'print("on windows")'
108
109 Supports simple factors (``django50:``), multiple factors (``py313,py312:``), and negation (``!lint:``). Any
110 multi-line setting (``deps``, ``commands``, ``set_env``, etc.) can use factor conditions.
111
112 Platform factors work in any environment without requiring the platform name in the environment name.
113
114 **Generative environment lists** -- Both INI and TOML support generating environment lists from factor combinations.
115
116 .. tab:: TOML
117
118 .. code-block:: toml
119
120 env_list = [
121 "lint",
122 { prefix = "3.", start = 12, stop = 14 },
123 { product = [["3.12", "3.13", "3.14"], ["django42", "django50"]] },
124 ]
125
126 Each ``env_list`` item is one of four structured shapes: a literal string, a bare range dict
127 (``{ prefix = "3.", start = 12, stop = 14 }``) for a single axis, a labeled dict
128 (``{ ecosystem = ["oci", "python"] }``) that also registers a ``{factor:label}`` name, or a ``product`` dict
129 that computes the Cartesian product of multiple factor groups and joins each combination with ``-``.
130 A ``product`` dict also accepts an ``exclude`` key to skip specific combinations. TOML never interprets curly
131 braces inside string items — composition is always via these dicts.
132
133 .. tab:: INI
134
135 .. code-block:: ini
136
137 [tox]
138 env_list = py3{12,13,14}-django{42,50}
139
140 Curly-brace expressions expand into the Cartesian product of all combinations. This generates 6 environments:
141 ``py312-django42``, ``py312-django50``, ..., ``py314-django50``. Ranges are also supported: ``py3{12-14}`` expands
142 to ``py312``, ``py313``, ``py314``. Open-ended ranges expand to the `supported CPython versions
143 <https://devguide.python.org/versions/>`_ at the time of the tox release: ``py3{10-}`` expands up to the latest
144 supported version, ``py3{-13}`` expands down to the oldest supported one.
145
146 **Generative section names** -- INI section headers can use the same curly-brace expansion:
147
148 .. code-block:: ini
149
150 [testenv:py3{12,13}-{x86,x64}]
151 envdir =
152 x86: .venv-x86
153 x64: .venv-x64
154
155 TOML does not support generative section names, but you can use ``env_base`` templates (see :ref:`env-base-templates`)
156 to generate multiple environments from a single definition:
157
158 .. code-block:: toml
159
160 [env_base.build]
161 factors = [["py312", "py313"], ["x86", "x64"]]
162 env_dir = { replace = "if", condition = "factor.x86", then = ".venv-x86", "else" = ".venv-x64" }
163 commands = [["python", "-c", "print('ok')"]]
164
165 This generates ``build-py312-x86``, ``build-py312-x64``, ``build-py313-x86``, ``build-py313-x64`` -- each inheriting
166 from the template and resolving factor conditions per environment.
167
168 .. _env-base-templates:
169
170 Environment base templates
171 --------------------------
172
173 ``env_base`` sections define named templates that generate multiple environments from factor combinations. Each template
174 requires a ``factors`` key -- a list of factor groups whose Cartesian product determines which environments are created.
175 The template name is joined with each factor combination using ``-``:
176
177 .. code-block:: toml
178
179 [env_base.test]
180 factors = [["3.13", "3.14"]]
181 deps = ["pytest>=8"]
182 commands = [["pytest"]]
183
184 This generates ``test-3.13`` and ``test-3.14``. For multi-dimensional matrices:
185
186 .. code-block:: toml
187
188 [env_base.django]
189 factors = [["py312", "py313"], ["django42", "django50"]]
190 deps = [
191 "pytest",
192 { replace = "if", condition = "factor.django42", then = ["Django>=4.2,<4.3"], extend = true },
193 { replace = "if", condition = "factor.django50", then = ["Django>=5.0,<5.1"], extend = true },
194 ]
195 commands = [["pytest"]]
196
197 This generates 4 environments: ``django-py312-django42``, ``django-py312-django50``, ``django-py313-django42``,
198 ``django-py313-django50``.
199
200 **Inheritance chain:** settings resolve in this order: ``[env.{name}]`` (explicit overrides) → ``[env_base.{template}]``
201 (template defaults) → ``[env_run_base]`` (global defaults).
202
203 **Factor groups** can be:
204
205 - A list of strings: ``["a", "b"]``
206 - A range dict: ``{ prefix = "py3", start = 12, stop = 14 }`` (generates ``py312``, ``py313``, ``py314``)
207 - A labeled dict: ``{ ecosystem = ["oci", "python"] }`` (same as a list, but registers the label for substitution)
208 - Mixed in the same ``factors`` list for Cartesian products
209
210 The template name itself does not appear as a runnable environment -- only the generated names do.
211
212 .. _factor-label-substitution:
213
214 Factor label substitution
215 ^^^^^^^^^^^^^^^^^^^^^^^^^
216
217 .. versionadded:: 4.49.0
218
219 Factor groups can be labeled by using a single-key dict instead of a plain list. The label enables ``{factor:label}``
220 substitution in any string value (descriptions, commands, deps, set_env, etc.), resolving to whichever value from the
221 labeled group is an active factor in the current environment. Every factor group also receives a positional label
222 (``0``, ``1``, ...) automatically.
223
224 **Named labels** -- use a single-key dict to name a factor group:
225
226 .. code-block:: toml
227
228 [env_base.sync]
229 factors = [{ecosystem = ["oci", "python", "js"]}, {target = ["pw", "tt"]}]
230 description = "Sync {factor:ecosystem} artifacts to {factor:target}"
231 commands = [["sync-tool", "--ecosystem", "{factor:ecosystem}"]]
232
233 For ``sync-oci-pw``, the description resolves to ``Sync oci artifacts to pw`` and the command receives ``--ecosystem
234 oci``.
235
236 **Positional labels** -- plain lists automatically get index-based labels:
237
238 .. code-block:: toml
239
240 [env_base.task]
241 factors = [["oci", "python"], ["pw", "tt"]]
242 description = "Run {factor:0} on {factor:1}"
243
244 For ``task-oci-pw``, the description resolves to ``Run oci on pw``. Labeled dicts also support positional access:
245 ``{factor:0}`` and ``{factor:ecosystem}`` both resolve to ``oci`` when the labeled dict is in position 0.
246
247 **In product matrices** -- labeled factor groups work in ``env_list`` product dicts too:
248
249 .. code-block:: toml
250
251 env_list = [
252 { product = [["sync"], {ecosystem = ["oci", "python"]}, {target = ["pw", "tt"]}] },
253 ]
254
255 [env_run_base]
256 description = "Sync {factor:ecosystem} to {factor:target}"
257
258 **Defaults** -- ``{factor:label:fallback}`` uses ``fallback`` when the label is unknown, following the same convention
259 as ``{env:VAR:default}``.
260
261 **Comparison with conditionals** -- ``{factor:label}`` replaces nested ``replace = "if"`` chains when the substituted
262 value equals the factor name itself. For values that don't match factor names (e.g., mapping ``pw`` to
263 ``production-west-cluster``), use ``replace = "if"`` with ``factor.NAME`` conditions.
264
265 **Reserved names** -- the following cannot be used as label names: ``env``, ``posargs``, ``tty``, ``glob``, ``factor``.
266
267 .. _tox-ini:
268
269 ``tox.ini``
270 ===========
271
272 This configuration file uses:
273
274 - ``tox`` section to host core configuration,
275 - ``testenv:{env_name}`` section to host environment configuration,
276 - ``testenv`` section as base configuration for run environments (fallback location for missing values for a test/run
277 environment),
278 - ``pkgenv`` section as base configuration for package environments (fallback location for missing values for a package
279 environment).
280
281 For example:
282
283 .. code-block:: ini
284
285 [tox]
286 requires =
287 tox >= 4.20
288 env_list =
289 3.14t
290 3.14
291 3.13
292 3.12
293 type
294
295 [testenv]
296 deps = pytest
297 commands = pytest tests
298
299 [testenv:type]
300 deps = mypy
301 commands = mypy src
302
303 ``setup.cfg``
304 =============
305
306 This configuration file uses:
307
308 - ``tox:tox`` section to host core configuration,
309 - ``testenv:{env_name}`` section to host environment configuration,
310 - ``testenv`` section as base configuration for run environments (fallback location for missing values for a test/run
311 environment),
312 - ``pkgenv`` section as base configuration for package environments (fallback location for missing values for a package
313 environment).
314
315 .. code-block:: ini
316
317 [tox:tox]
318 requires =
319 tox >= 4.0
320 env_list =
321 3.14t
322 3.14
323 3.13
324 3.12
325 type
326
327 [testenv]
328 deps = pytest
329 commands = pytest tests
330
331 [testenv:type]
332 deps = mypy
333 commands = mypy src
334
335 ``pyproject.toml`` - INI
336 ========================
337
338 This configuration file is equivalent to :ref:`tox.ini <tox-ini>` format, with the difference that the text is stored
339 instead inside the ``pyproject.toml`` file under the ``tool.tox`` table and ``legacy_tox_ini`` key:
340
341 .. code-block:: toml
342
343 [tool.tox]
344 legacy_tox_ini = """
345 [tox]
346 requires =
347 tox >= 4.0
348 env_list =
349 3.14
350 3.13
351 3.12
352 type
353
354 [testenv]
355 deps = pytest
356 commands = pytest tests
357
358 [testenv:type]
359 deps = mypy
360 commands = mypy src
361 """
362
363 .. _pyproject-toml-native:
364
365 ``pyproject.toml`` - native
366 ===========================
367
368 We support native TOML configuration via the ``pyproject.toml`` files ``tool.tox`` table. This configuration file uses:
369
370 - ``tool.tox`` table to host core configuration,
371 - ``tool.tox.env.{env_name}`` table to host environment configuration,
372 - ``tool.tox.env_run_base`` table as base configuration for run environments (fallback location for missing values for a
373 test/run environment),
374 - ``tool.tox.env_pkg_base`` table as base configuration for package environments (fallback location for missing values
375 for a package environment).
376
377 .. code-block:: toml
378
379 [tool.tox]
380 requires = ["tox>=4.19"]
381 env_list = ["3.14t", "3.14", "3.13", "3.12", "type"]
382
383 [tool.tox.env_run_base]
384 description = "Run test under {base_python}"
385 commands = [["pytest"]]
386
387 [tool.tox.env.type]
388 description = "run type check on code base"
389 deps = ["mypy==1.18.2", "types-cachetools>=5.5.0.20240820", "types-chardet>=5.0.4.6"]
390 commands = [["mypy", "src{/}tox"], ["mypy", "tests"]]
391
392 ``tox.toml``
393 ============
394
395 This configuration file is equivalent to :ref:`pyproject.toml - native <pyproject-toml-native>` with the difference that
396 it lives in a separate dedicated files and accordingly the ``tool.tox`` sub-table is no longer required.
397
398 For example:
399
400 .. code-block:: toml
401
402 requires = ["tox>=4.19"]
403 env_list = ["3.14t", "3.14", "3.13", "3.12", "type"]
404
405 [env_run_base]
406 description = "Run test under {base_python}"
407 commands = [["pytest"]]
408
409 [env.type]
410 description = "run type check on code base"
411 deps = ["mypy==1.18.2", "types-cachetools>=5.5.0.20240820", "types-chardet>=5.0.4.6"]
412 commands = [["mypy", "src{/}tox"], ["mypy", "tests"]]
413
414 .. _conf-core:
415
416 ******
417 Core
418 ******
419
420 The following options are set in the ``[tox]`` section of ``tox.ini``, the ``[tox:tox]`` section of ``setup.cfg``, or
421 the top level of ``tox.toml``. Placing these options in an environment section (e.g. ``[testenv]``) has no effect. Run
422 ``tox config`` or ``tox run -v`` to check for misplaced keys.
423
424 .. conf::
425 :keys: requires
426 :default: <empty list>
427 :version_added: 3.2.0
428
429 Specify a list of :pep:`508` compliant dependencies that must be satisfied in the Python environment hosting tox when
430 running the tox command. If any of these dependencies are not satisfied will automatically create a provisioned tox
431 environment that does not have this issue, and run the tox command within that environment. See
432 :ref:`provision_tox_env` for more details.
433
434 .. tab:: TOML
435
436 .. code-block:: toml
437
438 [tool.tox]
439 requires = [
440 "tox>=4",
441 "virtualenv>20.2",
442 ]
443
444 .. tab:: INI
445
446 .. code-block:: ini
447
448 [tox]
449 requires =
450 tox>=4
451 virtualenv>20.2
452
453 .. conf::
454 :keys: min_version, minversion
455 :default: <current version of tox>
456 :version_deprecated: 4.28.0
457 :version_added: 2.4
458
459 **DEPRECATED** Prefer requiring a minimum tox version via :ref:`requires`.
460
461 A string to define the minimal tox version required to run. If the host's tox version is less than this, it will
462 automatically create a provisioned tox environment that satisfies this requirement. See :ref:`provision_tox_env`
463 for more details.
464
465 .. conf::
466 :keys: provision_tox_env
467 :default: .tox
468 :version_added: 3.8.0
469
470 Name of the tox environment used to provision a valid tox run environment.
471
472 .. note::
473
474 The provisioning environment does not inherit settings from ``env_run_base`` (TOML) or ``[testenv]`` (INI).
475 It must be explicitly configured if you need to customize it (e.g. ``env.".tox"`` in TOML or
476 ``[testenv:.tox]`` in INI).
477
478 .. versionchanged:: 3.23.0
479
480 When tox is invoked with the ``--no-provision`` flag, the provision won't be attempted, tox will fail instead.
481
482 .. conf::
483 :keys: env_list, envlist
484 :default: <empty list>
485 :version_added: 1.0
486
487 A list of environments to run by default (when the user does not specify anything during the invocation).
488
489 .. versionchanged:: 3.4.0
490
491 Which tox environments are run during the tox invocation can be further filtered via the operating system
492 environment variable ``TOX_SKIP_ENV`` regular expression (e.g. ``py27.*`` means **don't** evaluate environments
493 that start with the key ``py27``). Skipped environments will be logged at level two verbosity level.
494
495 .. conf::
496 :keys: skip_missing_interpreters
497 :default: config
498 :version_added: 1.7.2
499
500 Setting this to ``true`` will force ``tox`` to return success even if some of the specified environments were
501 missing. This is useful for some CI systems or when running on a developer box, where you might only have a subset
502 of all your supported interpreters installed but don't want to mark the build as failed because of it. As expected,
503 the command line switch always overrides this setting if passed on the invocation. Setting it to ``config`` means
504 that the value is read from the config file.
505
506 .. conf::
507 :keys: tox_root, toxinidir
508 :version_added: 1.6.1
509
510 The root directory for the tox project (where the configuration file is found).
511
512 .. conf::
513 :keys: work_dir, toxworkdir
514 :default: {tox_root}/.tox
515 :version_added: 1.0
516
517 Directory for tox to generate its environments into, will be created if it does not exist.
518
519 .. conf::
520 :keys: temp_dir
521 :default: {work_dir}/.tmp
522 :version_added: 3.5
523
524 Directory where to put tox temporary files. For example: we create a hard link (if possible, otherwise new copy) in
525 this directory for the project package. This ensures tox works correctly when having parallel runs (as each session
526 will have its own copy of the project package - e.g. the source distribution).
527
528 .. conf::
529 :keys: no_package, skipsdist
530 :default: false
531 :version_added: 1.6
532
533 Flag indicating to perform the packaging operation or not. Set it to ``true`` when using tox for an application,
534 instead of a library.
535
536 .. conf::
537 :keys: package_env, isolated_build_env
538 :default: .pkg
539 :version_added: 3.3.0
540
541 Default name of the virtual environment used to create a source distribution from the source tree.
542
543 .. conf::
544 :keys: package_root, setupdir
545 :default: {tox_root}
546 :version_added: 1.0
547
548 Indicates where the packaging root file exists (historically setup.py file or pyproject.toml now).
549
550 .. conf::
551 :keys: labels
552 :default: <empty dictionary>
553 :version_added: 4.0
554
555 A mapping of label names to environments it applies too. For example:
556
557 .. tab:: TOML
558
559 .. code-block:: toml
560
561 [tool.tox]
562 labels = { test = ["3.14t", "3.14", "3.13", "3.12"], static = ["ruff", "mypy"] }
563
564 .. tab:: INI
565
566 .. code-block:: ini
567
568 [tox]
569 labels =
570 test = 3.14t, 3.14, 3.13, 3.12
571 static = ruff, mypy
572
573 .. conf::
574 :keys: on_platform
575 :constant:
576 :version_added: 4.17
577
578 A constant holding the platform of the tox runtime environment.
579
580 Python language core options
581 ============================
582
583 .. conf::
584 :keys: ignore_base_python_conflict, ignore_basepython_conflict
585 :default: False
586 :version_added: 3.1
587
588 .. versionadded:: 3.1.0
589
590 tox allows setting the Python version for an environment via the :ref:`base_python` setting. If that's not set tox
591 can set a default value from the environment name (e.g. ``3.10`` or ``py310`` implies Python 3.10). Matching up the Python
592 version with the environment name has became expected at this point, leading to surprises when some configs don't
593 do so. To help with sanity of users, an error will be raised whenever the environment name version does not match
594 up with this expectation.
595
596 Furthermore, we allow hard enforcing this rule by setting this flag to ``true``. In such cases we ignore the
597 :ref:`base_python` and instead always use the base Python implied from the Python name. This allows you to configure
598 :ref:`base_python` in the :ref:`base` section without affecting environments that have implied base Python versions.
599
600 **This flag handles two types of conflicts:**
601
602 1. **Explicit setting vs. environment name**: When :ref:`base_python` is explicitly set but conflicts with the
603 version extracted from the environment name. Setting this to ``true`` uses the version from the environment name.
604
605 2. **Multiple version factors in environment name** (since 4.47.3): When the environment name itself contains
606 multiple factors that look like Python versions (e.g., ``unit-py3.10-2.16`` where both ``py3.10`` and ``2.16``
607 match Python version patterns). Setting this to ``true`` falls back to :ref:`default_base_python` instead of
608 raising an error. To avoid this ambiguity, prefix non-Python version factors (e.g. use ``ac2.16`` instead of
609 ``2.16``).
610
611 .. _conf-testenv:
612
613 *****************
614 tox environment
615 *****************
616
617 These are configuration for the tox environments (either packaging or run type). Set these in ``[testenv]`` (INI),
618 ``env_run_base`` (TOML), or per-environment sections. Placing these options in the core ``[tox]`` section has no effect.
619 Run ``tox config`` or ``tox run -v`` to check for misplaced keys.
620
621 Base options
622 ============
623
624 .. conf::
625 :keys: envname, env_name
626 :constant:
627 :version_added: 4.0
628
629 The name of the tox environment.
630
631 .. conf::
632 :keys: env_dir, envdir
633 :default: {work_dir}/{env_name}
634 :version_added: 1.5
635
636 Directory assigned to the tox environment. If not absolute it would be treated as relative to :ref:`tox_root`.
637
638 .. conf::
639 :keys: env_tmp_dir, envtmpdir
640 :default: {work_dir}/{env_name}/tmp
641 :version_added: 0.5
642
643 A folder that is always reset at the start of the run.
644
645 .. conf::
646 :keys: env_log_dir, envlogdir
647 :default: {work_dir}/{env_name}/log
648 :version_added: 0.5
649
650 A folder containing log files about tox runs. It's always reset at the start of the run. Currently contains every
651 process invocation in the format of ``<index>-<run name>.log``, and details the execution request (command,
652 environment variables, current working directory, etc.) and its outcome (exit code and standard output/error
653 content).
654
655 .. conf::
656 :keys: platform
657 :version_added: 2.0
658
659 Run on platforms that match this regular expression (empty means any platform). If a non-empty expression is defined
660 and does not match against the ``sys.platform`` string the entire test environment will be skipped and none of the
661 commands will be executed. Running ``tox -e <platform_name>`` will run commands for a particular platform and skip
662 the rest.
663
664 .. conf::
665 :keys: pass_env, passenv
666 :default: <empty list>
667 :version_added: 2.0
668
669 Environment variables to pass on to the tox environment. The values are evaluated as UNIX shell-style wildcards, see
670 `fnmatch <https://docs.python.org/3/library/fnmatch.html>`_ If a specified environment variable doesn't exist in the
671 tox invocation environment it is ignored. The list of environment variable names is not case sensitive, for example:
672 passing ``A`` or ``a`` will pass through both ``A`` and ``a``.
673
674 Some variables are always passed through to ensure the basic functionality of standard library functions or tooling like
675 pip. This is also not case sensitive on all platforms except Windows.
676
677 .. list-table:: Environment Variables per Operating System
678 :widths: 25 25 25 25
679 :header-rows: 1
680
681 * - Environment Variable
682 - Linux
683 - MacOS
684 - Windows
685 * - https_proxy
686 - ✅
687 - ✅
688 - ✅
689 * - http_proxy
690 - ✅
691 - ✅
692 - ✅
693 * - no_proxy
694 - ✅
695 - ✅
696 - ✅
697 * - LANG
698 - ✅
699 - ✅
700 - ✅
701 * - LANGUAGE
702 - ✅
703 - ✅
704 - ✅
705 * - CURL_CA_BUNDLE
706 - ✅
707 - ✅
708 - ✅
709 * - SSL_CERT_FILE
710 - ✅
711 - ✅
712 - ✅
713 * - CC
714 - ✅
715 - ✅
716 - ✅
717 * - CFLAGS
718 - ✅
719 - ✅
720 - ✅
721 * - CCSHARED
722 - ✅
723 - ✅
724 - ✅
725 * - CXX
726 - ✅
727 - ✅
728 - ✅
729 * - CPPFLAGS
730 - ✅
731 - ✅
732 - ✅
733 * - LD_LIBRARY_PATH
734 - ✅
735 - ✅
736 - ✅
737 * - LDFLAGS
738 - ✅
739 - ✅
740 - ✅
741 * - HOME
742 - ✅
743 - ✅
744 - ✅
745 * - FORCE_COLOR
746 - ✅
747 - ✅
748 - ✅
749 * - NO_COLOR
750 - ✅
751 - ✅
752 - ✅
753 * - TMPDIR
754 - ✅
755 - ✅
756 - ❌
757 * - TEMP
758 - ❌
759 - ❌
760 - ✅
761 * - TMP
762 - ❌
763 - ❌
764 - ✅
765 * - USERPROFILE
766 - ❌
767 - ❌
768 - ✅
769 * - PATHEXT
770 - ❌
771 - ❌
772 - ✅
773 * - MSYSTEM
774 - ❌
775 - ❌
776 - ✅
777 * - WINDIR
778 - ❌
779 - ❌
780 - ✅
781 * - APPDATA
782 - ❌
783 - ❌
784 - ✅
785 * - LOCALAPPDATA
786 - ❌
787 - ❌
788 - ✅
789 * - PROGRAMDATA
790 - ❌
791 - ❌
792 - ✅
793 * - PROGRAMFILES(x86)
794 - ❌
795 - ❌
796 - ✅
797 * - SYSTEMDRIVE
798 - ❌
799 - ❌
800 - ✅
801 * - SYSTEMROOT
802 - ❌
803 - ❌
804 - ✅
805 * - COMSPEC
806 - ❌
807 - ❌
808 - ✅
809 * - PROCESSOR_ARCHITECTURE
810 - ❌
811 - ❌
812 - ✅
813 * - NUMBER_OF_PROCESSORS
814 - ❌
815 - ❌
816 - ✅
817 * - PIP_*
818 - ✅
819 - ✅
820 - ✅
821 * - VIRTUALENV_*
822 - ✅
823 - ✅
824 - ✅
825 * - NETRC
826 - ✅
827 - ✅
828 - ✅
829 * - NIX_LD*
830 - ✅
831 - ✅
832 - ❌
833 * - NIX_LD_LIBRARY_PATH
834 - ✅
835 - ✅
836 - ❌
837 * - PYTHON_GIL
838 - ✅
839 - ✅
840 - ✅
841 * - SSH_AGENT_PID
842 - ✅
843 - ✅
844 - ❌
845 * - SSH_AUTH_SOCK
846 - ✅
847 - ✅
848 - ❌
849
850 If the environment variable ``CI`` is present, ``__TOX_ENVIRONMENT_VARIABLE_ORIGINAL_CI`` will be set to the value of ``CI``. The ``CI`` variable itself will not be passed through.
851
852 More environment variable-related information can be found in :ref:`environment variable substitutions`.
853
854 .. conf::
855 :keys: disallow_pass_env
856 :default: <empty list>
857 :version_added: 4.36
858
859 Environment variable patterns to exclude after :ref:`pass_env` glob expansion. Uses the same
860 :py:mod:`fnmatch` wildcard syntax as ``pass_env``. Applied after ``pass_env`` patterns are resolved against the
861 host environment and before ``set_env`` values are applied:
862
863 .. tab:: TOML
864
865 .. code-block:: toml
866
867 [env_run_base]
868 pass_env = ["FOO_*"]
869 disallow_pass_env = ["FOO_SECRET"]
870
871 .. tab:: INI
872
873 .. code-block:: ini
874
875 [testenv]
876 pass_env = FOO_*
877 disallow_pass_env = FOO_SECRET
878
879 In this example, all environment variables matching ``FOO_*`` are passed through except ``FOO_SECRET``.
880
881 .. conf::
882 :keys: set_env, setenv
883 :version_added: 1.0
884
885 A dictionary of environment variables to set when running commands in the tox environment.
886
887 In addition, there is an option to include an existing environment file. See the different syntax for TOML and INI below.
888
889 .. tab:: TOML
890
891 .. code-block:: toml
892
893 [tool.tox.env_run_base]
894 set_env = { file = "conf{/}local.env", TEST_TIMEOUT = "30" }
895
896 .. tab:: INI
897
898 .. code-block:: ini
899
900 [testenv]
901 set_env = file|conf{/}local.env
902 TEST_TIMEOUT = 30
903
904
905 The env file path may include previously defined tox variables:
906
907
908 .. tab:: TOML
909
910 .. code-block:: toml
911
912 [tool.tox.env_run_base]
913 set_env = { file = "{env:variable}" }
914
915 .. tab:: INI
916
917 .. code-block:: ini
918
919 [testenv]
920 set_env = file|{env:variable}
921
922
923 .. note::
924
925 Environment files are processed using the following rules:
926
927 - blank lines are ignored,
928 - lines starting with the ``#`` character are ignored,
929 - each line is in KEY=VALUE format; both the key and the value are stripped,
930 - there is no special handling of quotation marks, they are part of the key or value.
931
932 **Conditional environment variables**
933
934 .. versionadded:: 4.33
935
936 Environment variables can be set conditionally based on PEP-508 environment markers. If the marker evaluates to
937 false, the variable will not be set.
938
939 .. note::
940
941 Markers are evaluated against the Python interpreter running tox (the host Python), not the target environment's
942 Python interpreter. This means markers like ``python_version`` reflect tox's Python version, not the target's.
943 For platform-specific conditions (e.g., ``sys_platform``, ``os_name``), this is typically the desired behavior
944 since the target environment runs on the same platform.
945
946 .. tab:: TOML
947
948 .. code-block:: toml
949
950 [tool.tox.env_run_base]
951 set_env.LINUX_VAR = { value = "1", marker = "sys_platform == 'linux'" }
952 set_env.WIN_VAR = { value = "1", marker = "sys_platform == 'win32'" }
953
954 # Can also be combined with replace directives
955 set_env.CONDITIONAL = { replace = "env", name = "MY_VAR", default = "fallback", marker = "sys_platform == 'linux'" }
956
957 .. tab:: INI
958
959 .. code-block:: ini
960
961 [testenv]
962 set_env =
963 LINUX_VAR = 1; sys_platform == 'linux'
964 DARWIN_VAR = 1; sys_platform == 'darwin'
965 WIN_ONLY = 1; sys_platform == 'win32'
966
967 Available markers include ``sys_platform``, ``os_name``, ``platform_machine``, ``platform_system``,
968 ``python_version``, ``implementation_name``, and others as defined in PEP-508.
969
970 For conditional settings that should differ per target Python environment (e.g., based on Python version), use
971 tox's :ref:`conditional settings <conditional-settings>` mechanism with environment factors instead.
972
973 .. note::
974
975 Changing installer-relevant environment variables via ``set_env`` (e.g. ``PIP_INDEX_URL``,
976 ``PIP_EXTRA_INDEX_URL``) invalidates the install cache and triggers a reinstall on the next
977 run. Only variables known to affect package resolution are tracked; cosmetic or performance
978 variables such as ``PIP_TIMEOUT`` or ``PIP_VERBOSE`` do not affect the cache.
979 Plugin-based installers (e.g. ``tox-uv``) extend this list with their own
980 resolution-affecting variables.
981
982 More environment variable-related information
983 can be found in :ref:`environment variable substitutions`.
984
985 .. _injected-environment-variables:
986
987 Injected environment variables
988 ------------------------------
989
990 tox automatically injects several environment variables into the test environment when running commands. These are
991 always set regardless of the ``pass_env`` or ``set_env`` configuration and cannot be overridden by the user.
992
993 .. list-table::
994 :widths: 30 70
995 :header-rows: 1
996
997 - - Variable
998 - Description
999 - - ``TOX_ENV_NAME``
1000 - The name of the current tox environment (e.g. ``3.12``, ``lint``).
1001 - - ``TOX_WORK_DIR``
1002 - The tox working directory (by default ``.tox`` under the project root).
1003 - - ``TOX_ENV_DIR``
1004 - The directory of the current tox environment (e.g. ``.tox/3.12``).
1005 - - ``PYTHONIOENCODING``
1006 - Always set to ``utf-8`` to ensure consistent encoding for standard I/O.
1007 - - ``PIP_USER``
1008 - Always set to ``0`` to prevent pip from attempting ``--user`` installs inside virtualenvs, which would fail
1009 because user site-packages aren't visible. Only set when using ``virtualenv``\-based environments.
1010 - - ``TOX_PACKAGE``
1011 - The path(s) to the built package artifact(s), joined by ``os.pathsep`` if there are multiple. Only set in run
1012 environments where a package has been built. See :ref:`howto-reference-built-package` for usage examples.
1013 - - ``VIRTUAL_ENV``
1014 - The path to the virtual environment directory. Only set when using ``virtualenv``\-based environments (the
1015 default).
1016 - - ``__TOX_ENVIRONMENT_VARIABLE_ORIGINAL_CI``
1017 - The value of the ``CI`` environment variable from the host. Only set when the ``CI`` variable is present in the
1018 host environment.
1019
1020 .. note::
1021
1022 In tox 3, ``TOX_PARALLEL_ENV`` was injected during parallel runs. This variable is **no longer injected** in tox 4.
1023
1024 .. conf::
1025 :keys: parallel_show_output
1026 :default: False
1027 :version_added: 3.7
1028
1029 If set to ``True`` the content of the output will always be shown when running in parallel mode.
1030
1031 .. conf::
1032 :keys: recreate
1033 :default: False
1034 :version_added: 0.9
1035
1036 Always recreate virtual environment if this option is true, otherwise leave it up to tox.
1037
1038 .. conf::
1039 :keys: allowlist_externals
1040 :default: <empty list>
1041 :version_added: 1.5
1042
1043 Each line specifies a command name (in glob-style pattern format) which can be used in the commands section even if
1044 it's located outside of the tox environment. For example: if you use the unix *rm* command for running tests you can
1045 list ``allowlist_externals=rm`` or ``allowlist_externals=/usr/bin/rm``. If you want to allow all external
1046 commands you can use ``allowlist_externals=*`` which will match all commands (not recommended).
1047
1048 .. conf::
1049 :keys: labels
1050 :default: <empty list>
1051 :ref_suffix: env
1052 :version_added: 4.0
1053
1054 A list of labels to apply for this environment. For example:
1055
1056 .. tab:: TOML
1057
1058 .. code-block:: toml
1059
1060 [tool.tox.env_run_base]
1061 labels = ["test", "core"]
1062 [tool.tox.env.flake8]
1063 labels = ["mypy"]
1064
1065 .. tab:: INI
1066
1067 .. code-block:: ini
1068
1069 [testenv]
1070 labels = test, core
1071 [testenv:flake8]
1072 labels = mypy
1073
1074 Execute
1075 =======
1076
1077 .. conf::
1078 :keys: suicide_timeout
1079 :default: 0.0
1080 :version_added: 3.15.2
1081
1082 When an interrupt is sent via Ctrl+C or the tox process is killed with a SIGTERM, a SIGINT is sent to all foreground
1083 processes. The :ref:`suicide_timeout` gives the running process time to cleanup and exit before receiving (in some
1084 cases, a duplicate) SIGINT from tox.
1085
1086 .. conf::
1087 :keys: interrupt_timeout
1088 :default: 0.3
1089 :version_added: 3.15
1090
1091 When tox is interrupted, it propagates the signal to the child process after :ref:`suicide_timeout` seconds. If the
1092 process still hasn't exited after :ref:`interrupt_timeout` seconds, its sends a SIGTERM.
1093
1094 .. conf::
1095 :keys: terminate_timeout
1096 :default: 0.2
1097 :version_added: 3.15
1098
1099 When tox is interrupted, after waiting :ref:`interrupt_timeout` seconds, it propagates the signal to the child
1100 process, waits :ref:`interrupt_timeout` seconds, sends it a SIGTERM, waits :ref:`terminate_timeout` seconds, and
1101 sends it a SIGKILL if it hasn't exited.
1102
1103 Run
1104 ===
1105
1106 .. conf::
1107 :keys: base
1108 :default: testenv
1109 :version_added: 4.0.0
1110
1111 Inherit missing keys from these sections.
1112
1113 .. conf::
1114 :keys: runner
1115 :default:
1116 :version_added: 4.0.0
1117
1118 The tox execute used to evaluate this environment. Defaults to Python virtual environments, however may be
1119 overwritten by plugins. Set to ``virtualenv-pep-723`` to use inline script metadata (see :ref:`script`).
1120
1121 .. conf::
1122 :keys: script
1123 :default: <empty string>
1124 :version_added: 4.52
1125
1126 Path to a Python script with :PEP:`723` inline metadata, relative to :ref:`tox_root`. Only available when
1127 ``runner = virtualenv-pep-723``. The script's ``requires-python`` and ``dependencies`` fields drive the environment's
1128 Python version and installed packages. ``commands`` defaults to running the script with ``{posargs}`` forwarded, but
1129 can be overridden. See :ref:`pep723-explanation` for details.
1130
1131 .. tab:: TOML
1132
1133 .. code-block:: toml
1134
1135 [env.check]
1136 runner = "virtualenv-pep-723"
1137 script = "tools/check.py"
1138
1139 .. tab:: INI
1140
1141 .. code-block:: ini
1142
1143 [testenv:check]
1144 runner = virtualenv-pep-723
1145 script = tools/check.py
1146
1147 .. conf::
1148 :keys: description
1149 :default: <empty string>
1150 :version_added: 2.7
1151
1152 A short description of the environment, this will be used to explain the environment to the user upon listing
1153 environments.
1154
1155 .. conf::
1156 :keys: depends
1157 :default: <empty list>
1158 :version_added: 3.7
1159
1160 tox environments that this environment depends on (must be run after those). Supports glob patterns using
1161 :py:mod:`fnmatch` syntax to match environment names dynamically:
1162
1163 - ``*`` matches everything (e.g. ``3.*`` matches ``3.12``, ``3.13``, ``3.14``)
1164 - ``?`` matches any single character (e.g. ``py?`` matches ``py3`` but not ``py314``)
1165 - ``[seq]`` matches any character in *seq* (e.g. ``lint-[ab]`` matches ``lint-a`` and ``lint-b``)
1166 - ``[!seq]`` matches any character not in *seq*
1167
1168 .. tab:: TOML
1169
1170 .. code-block:: toml
1171
1172 [env.coverage]
1173 depends = ["3.*"]
1174
1175 .. tab:: INI
1176
1177 .. code-block:: ini
1178
1179 [testenv:coverage]
1180 depends = 3.*
1181
1182 This matches all environments whose name starts with ``3.`` (e.g. ``3.12``, ``3.13``, ``3.14``). Glob patterns are
1183 resolved at runtime against the set of environments being run, so adding a new environment to ``env_list``
1184 automatically includes it in the dependency without updating ``depends``. Self-matches are excluded, so
1185 ``depends = *`` will depend on all other environments without creating a cycle.
1186
1187 .. warning::
1188
1189 ``depends`` does not pull in dependencies into the run target, for example if you select ``3.13,3.12,coverage``
1190 via the ``-e`` tox will only run those three (even if ``coverage`` may specify as ``depends`` other targets too -
1191 such as ``3.13, 3.12, 3.11``). This is solely meant to specify dependencies and order in between a target run
1192 set.
1193
1194 .. conf::
1195 :keys: extra_setup_commands
1196 :default: <empty list>
1197 :version_added: 4.37
1198
1199 Commands to execute after the setup phase (dependencies and package installation) but before test commands.
1200 These commands run during the ``--notest`` phase, making them useful for separating environment setup from
1201 test execution. All evaluation and configuration logic applies from :ref:`commands`.
1202
1203 This is particularly useful when you want to use ``tox run --notest`` to set up the environment and install
1204 additional tools or perform setup tasks, while keeping the actual test execution separate.
1205
1206 For example, to install pre-commit hooks during the setup phase:
1207
1208 .. tab:: TOML
1209
1210 .. code-block:: toml
1211
1212 [tool.tox.env_run_base]
1213 deps = ["pre-commit"]
1214 extra_setup_commands = [
1215 ["pre-commit", "install-hooks"],
1216 ]
1217 commands = [
1218 ["pre-commit", "run", "--all-files"],
1219 ]
1220
1221 .. tab:: INI
1222
1223 .. code-block:: ini
1224
1225 [testenv]
1226 deps = pre-commit
1227 extra_setup_commands = pre-commit install-hooks
1228 commands = pre-commit run --all-files
1229
1230 When running ``tox run --notest``, the environment will be created, dependencies installed, and
1231 ``extra_setup_commands`` executed, but ``commands`` will be skipped. When running ``tox run`` without
1232 ``--notest``, all commands including ``extra_setup_commands`` will execute.
1233
1234 .. conf::
1235 :keys: recreate_commands
1236 :default: <empty list>
1237 :version_added: 4.42
1238
1239 Commands to run before the environment directory is removed during recreation (``tox run -r``). These commands
1240 execute inside the existing environment, so tools installed there are available. Useful for cleaning external caches
1241 managed by tools like pre-commit. Failures are logged as warnings but never block recreation.
1242
1243 .. tab:: TOML
1244
1245 .. code-block:: toml
1246
1247 [env_run_base]
1248 deps = ["pre-commit"]
1249 recreate_commands = [["{env_python}", "-Im", "pre_commit", "clean"]]
1250
1251 .. tab:: INI
1252
1253 .. code-block:: ini
1254
1255 [testenv]
1256 deps = pre-commit
1257 recreate_commands = {env_python} -Im pre_commit clean
1258
1259 These commands do **not** run on first creation (the environment directory does not exist yet) or on normal
1260 re-runs without ``-r``.
1261
1262 .. conf::
1263 :keys: commands_pre
1264 :default: <empty list>
1265 :version_added: 3.4
1266
1267 Commands to run before running the :ref:`commands`. All evaluation and configuration logic applies from
1268 :ref:`commands`.
1269
1270 .. conf::
1271 :keys: commands
1272 :default: <empty list>
1273 :version_added: 0.5
1274
1275 The commands to be called for testing. Only execute if :ref:`commands_pre` succeed. Each line is interpreted as one
1276 command; however a command can be split over multiple lines by ending the line with the ``\`` character.
1277
1278 Commands will execute one by one in sequential fashion until one of them fails (their exit code is non-zero) or all
1279 of them succeed. The exit code of a command may be ignored (meaning they are always considered successful) by
1280 prefixing the command with a dash (``-``) - this is similar to how ``make`` recipe lines work. The outcome of the
1281 environment is considered successful only if all commands (these + setup + teardown) succeeded (exit code ignored
1282 via the ``-`` or success exit code value of zero).
1283
1284 .. note::
1285
1286 The virtual environment binary path (see :ref:`env_bin_dir`) is prepended to the ``PATH`` environment variable,
1287 meaning commands will first try to resolve to an executable from within the virtual environment, and only after
1288 that outside of it. Therefore ``python`` translates as the virtual environments ``python`` (having the same
1289 runtime version as the :ref:`base_python`), and ``pip`` translates as the virtual environments ``pip``.
1290
1291 .. note::
1292
1293 ``shlex`` POSIX-mode quoting rules are used to split the command line into arguments on all
1294 supported platforms as of tox 4.4.0.
1295
1296 The backslash ``\`` character can be used to escape quotes, whitespace, itself, and
1297 other characters (except on Windows, where a backslash in a path will not be interpreted as an escape).
1298 Unescaped single quote will disable the backslash escape until closed by another unescaped single quote.
1299 For more details, please see :doc:`shlex parsing rules <python:library/shlex>`.
1300
1301 .. note::
1302
1303 Inline scripts can be used, however note these are discovered from the project root directory, and is not
1304 influenced by :ref:`change_dir` (this only affects the runtime current working directory). To make this behavior
1305 explicit we recommend that you make inline scripts absolute paths by prepending ``{tox_root}``, instead of
1306 ``path/to/my_script`` prefer ``{tox_root}{/}path{/}to{/}my_script``. If your inline script is platform dependent
1307 refer to :ref:`platform-specification` on how to select different script per platform.
1308
1309 .. conf::
1310 :keys: commands_post
1311 :default: <empty list>
1312 :version_added: 3.4
1313
1314 Commands to run after running the :ref:`commands`. Execute regardless of the outcome of both :ref:`commands` and
1315 :ref:`commands_pre`. All evaluation and configuration logic applies from :ref:`commands`.
1316
1317 .. conf::
1318 :keys: change_dir, changedir
1319 :default: {tox_root}
1320 :version_added: 0.5
1321
1322 Change to this working directory when executing the test command. If the directory does not exist yet, it will be
1323 created (required for Windows to be able to execute any command).
1324
1325 .. conf::
1326 :keys: args_are_paths
1327 :default: False
1328 :version_added: 0.5
1329
1330 Treat positional arguments passed to tox as file system paths and - if they exist on the filesystem and are in
1331 relative format - rewrite them according to the current and :ref:`change_dir` working directory. This handles
1332 automatically transforming relative paths specified on the CLI to relative paths respective of the commands executing
1333 directory.
1334
1335 .. conf::
1336 :keys: ignore_errors
1337 :default: False
1338 :version_added: 2.0
1339
1340 When executing the commands keep going even if a sub-command exits with non-zero exit code. The overall status will
1341 be "commands failed", i.e. tox will exit non-zero in case any command failed. It may be helpful to note that this
1342 setting is analogous to the ``-k`` or ``--keep-going`` option of GNU Make.
1343
1344 .. conf::
1345 :keys: commands_retry
1346 :default: 0
1347 :version_added: 4.41
1348
1349 Number of times to retry a failed command before giving up. A value of ``N`` means each command can be attempted up
1350 to ``N + 1`` times total. Applies to :ref:`commands_pre`, :ref:`commands`, and :ref:`commands_post`. Commands
1351 prefixed with ``-`` (ignore exit code) are never retried since their failures are already ignored.
1352
1353 .. tab:: TOML
1354
1355 .. code-block:: toml
1356
1357 [env_run_base]
1358 commands_retry = 2
1359 commands = [["pytest", "tests"]]
1360
1361 .. tab:: INI
1362
1363 .. code-block:: ini
1364
1365 [testenv]
1366 commands_retry = 2
1367 commands = pytest tests
1368
1369 .. conf::
1370 :keys: ignore_outcome
1371 :default: False
1372 :version_added: 2.2
1373
1374 If set to true a failing result of this test environment will not make tox fail (instead just warn).
1375
1376 .. conf::
1377 :keys: fail_fast
1378 :default: False
1379 :version_added: 4.36.0
1380
1381 If set to true, tox will stop executing remaining environments when this environment fails. This can also be
1382 enabled globally via the ``--fail-fast`` (``-x``) CLI flag. The behavior respects :ref:`ignore_outcome` --
1383 environments with ``ignore_outcome = true`` will not trigger fail-fast even if they fail.
1384
1385 .. conf::
1386 :keys: skip_install
1387 :default: False
1388 :version_added: 1.9
1389
1390 Skip installation of the package. This can be used when you need the virtualenv management but do not want to
1391 install the current package into that environment. To also skip dependency installation at runtime, use the
1392 ``--skip-env-install`` CLI flag (see :ref:`skip-env-install`).
1393
1394 .. conf::
1395 :keys: package_env
1396 :default: {package_env}
1397 :version_added: 4.0.0
1398 :ref_suffix: env
1399
1400 Name of the virtual environment used to create a source distribution from the source tree for this environment.
1401
1402 .. conf::
1403 :keys: package_tox_env_type
1404 :version_added: 4.0.0
1405 :default: virtualenv-pep-517
1406
1407 tox package type used to package.
1408
1409 .. _packaging-env-config:
1410
1411 Packaging environment configuration
1412 ===================================
1413
1414 Packaging environments (such as ``.pkg`` and ``.pkg-cpython314``) are tox environments used to build your project's
1415 package. Unlike run environments, packaging environments do **not** inherit from the ``env_run_base`` table (TOML) or
1416 ``[testenv]`` section (INI). This is intentional — test environment settings often conflict with packaging settings.
1417
1418 Instead, packaging environments inherit from the ``env_pkg_base`` table (TOML) or ``[pkgenv]`` section (INI). This
1419 allows you to define common packaging settings in one central place, while still overriding them for specific packaging
1420 environments when needed.
1421
1422 .. tab:: TOML
1423
1424 .. code-block:: toml
1425
1426 [env_pkg_base]
1427 pass_env = ["PKG_CONFIG", "PKG_CONFIG_PATH", "PKG_CONFIG_SYSROOT_DIR"]
1428
1429 [env.".pkg-cpython311"]
1430 pass_env = ["PKG_CONFIG", "PKG_CONFIG_PATH", "PKG_CONFIG_SYSROOT_DIR", "IS_311"]
1431
1432 .. tab:: INI
1433
1434 .. code-block:: ini
1435
1436 [pkgenv]
1437 pass_env =
1438 PKG_CONFIG
1439 PKG_CONFIG_PATH
1440 PKG_CONFIG_SYSROOT_DIR
1441
1442 [testenv:.pkg-cpython311]
1443 pass_env =
1444 {[pkgenv]pass_env}
1445 IS_311 = yes
1446
1447 .. note::
1448
1449 Specific packaging environments are defined under ``[testenv:.pkg]`` and **not** ``[pkgenv:.pkg]``. The ``[pkgenv]``
1450 section (or ``env_pkg_base`` in TOML) serves only as the base/fallback for settings shared across all packaging
1451 environments.
1452
1453 .. versionchanged:: 4.2
1454
1455 Packaging environments now inherit from the ``[pkgenv]`` / ``env_pkg_base`` section.
1456
1457 .. _python-options:
1458
1459 Python options
1460 ==============
1461
1462 .. conf::
1463 :keys: base_python, basepython
1464 :default: <{env_name} python factor> or <python version of tox>
1465 :version_added: 0.5
1466
1467 Name or path to a Python interpreter which will be used for creating the virtual environment, first one found wins.
1468 This determines in practice the Python for what we'll create a virtual isolated environment. Use this to specify the
1469 Python version for a tox environment. If not specified, the virtual environments factors (e.g. name part) will be
1470 used to automatically set one. For example, ``py310`` means ``python3.10``, ``py3`` means ``python3`` and ``py``
1471 means ``python``. If the name does not match this pattern, :ref:`default_base_python` is consulted, and if that is
1472 also not set, the same Python version tox is installed into will be used.
1473 A base interpreter ending with ``t`` means that only free threaded Python implementations are accepted.
1474
1475 The preferred naming convention is ``N.M`` (e.g. ``3.14``, ``3.13``) rather than ``pyNMM`` (e.g. ``py314``,
1476 ``py313``). The dotted form is clearer, avoids ambiguity for Python versions >= 3.10, and reads more naturally in
1477 environment lists and CI output.
1478
1479 .. warning::
1480
1481 Any factor matching the pattern ``2.N`` or ``3.N`` (where N is one or more digits) is treated as a Python
1482 version specifier. This means non-Python versions like ``2.16`` in an environment name such as
1483 ``unit-py3.10-2.16`` will conflict with the ``py3.10`` factor. To avoid this, prefix non-Python version numbers
1484 (e.g. ``ac2.16``), or set :ref:`ignore_base_python_conflict` to ``true``.
1485
1486 .. versionadded:: 4.46
1487
1488 You can append a CPU architecture (ISA) suffix to constrain the interpreter to a specific machine type. The
1489 architecture is derived from :func:`python:sysconfig.get_platform` and normalized by :pypi:`virtualenv` (e.g.
1490 ``amd64`` becomes ``x86_64``, ``aarch64`` becomes ``arm64``). Examples:
1491
1492 - ``cpython3.12-64-arm64`` — CPython 3.12, 64-bit, ARM
1493 - ``cpython3.13-64-x86_64`` — CPython 3.13, 64-bit, x86-64
1494
1495 If the discovered interpreter's architecture does not match the requested one, tox raises a failure, just as it
1496 does for version mismatches. This is useful on machines with multi-architecture support (e.g. Apple Silicon
1497 running both ``arm64`` and ``x86_64`` via Rosetta, or Linux with ``aarch64`` and ``x86_64`` via ``qemu-user``).
1498
1499 .. versionchanged:: 3.1
1500
1501 After resolving this value if the interpreter reports back a different version number than implied from the name
1502 a warning will be printed by default. However, if :ref:`ignore_basepython_conflict` is set, the value is
1503 ignored and we force the :ref:`base_python` implied from the factor name.
1504
1505 .. note::
1506
1507 Leaving this unset will cause an error if the package under test has a different Python requires than tox itself
1508 and tox is installed into a Python that's not supported by the package. For example, if your package requires
1509 Python 3.10 or later, and you install tox in Python 3.9, when you run a tox environment that has left this
1510 unspecified tox will use Python 3.9 to build and install your package which will fail given it requires 3.10.
1511
1512 .. conf::
1513 :keys: default_base_python
1514 :default: <python version of tox>
1515 :version_added: 4.42
1516
1517 Fallback Python interpreter used when the environment name contains no Python factor and no explicit
1518 :ref:`base_python` is set. Accepts a list of specifications -- the first one found wins. This provides a way to
1519 pin a default Python version for reproducibility across different machines without conflicting with ``pyXY``
1520 factor-named environments.
1521
1522 The resolution order for an environment's Python interpreter is:
1523
1524 1. Python factor extracted from the environment name (e.g. ``3.13``, ``py313``)
1525 2. Explicit :ref:`base_python` setting on the environment
1526 3. :ref:`base_python_file` — read from a version file
1527 4. ``default_base_python`` (this setting)
1528 5. The Python running tox (``sys.executable``)
1529
1530 .. tab:: TOML
1531
1532 .. code-block:: toml
1533
1534 [env_run_base]
1535 default_base_python = ["3.14", "3.13"]
1536
1537 .. tab:: INI
1538
1539 .. code-block:: ini
1540
1541 [testenv]
1542 default_base_python = 3.14, 3.13
1543
1544 .. conf::
1545 :keys: base_python_file
1546 :default: <empty string>
1547 :version_added: 4.51
1548
1549 A path to a file containing the Python version to use for the environment (e.g. ``.python-version``). The first
1550 non-blank, non-comment line in the file is used as the Python version specifier. This is useful for tool
1551 environments (such as ``mypy`` or ``coverage``) where you want a single source of truth for the default Python
1552 version without hardcoding it in the tox configuration.
1553
1554 This option is only consulted when :ref:`base_python` is not explicitly set **and** the environment name does not
1555 contain a Python factor (e.g. ``py314``). See :ref:`default_base_python` for the full resolution order.
1556
1557 .. tab:: TOML
1558
1559 .. code-block:: toml
1560
1561 [env.mypy]
1562 base_python_file = [".python-version", ".python-version-default"]
1563
1564 .. tab:: INI
1565
1566 .. code-block:: ini
1567
1568 [testenv:mypy]
1569 base_python_file = .python-version, .python-version-default
1570
1571 The file format is the same as used by ``pyenv`` and GitHub Actions' ``python-version-file``: one version per file,
1572 lines starting with ``#`` are comments, blank lines are ignored.
1573
1574 .. conf::
1575 :keys: env_site_packages_dir, envsitepackagesdir
1576 :constant:
1577 :version_added: 1.4.3
1578
1579 The Python environments site package - where pure-python packages are installed (the purelib folder path).
1580
1581 .. conf::
1582 :keys: env_site_packages_dir_plat, envsitepackagesdir_plat
1583 :constant:
1584 :version_added: 4.42
1585
1586 The Python environments platform-specific site package (the platlib folder path). On most platforms this is the same
1587 as :ref:`env_site_packages_dir`, but on some Linux distributions (Fedora, RHEL) platlib resolves to ``lib64`` instead
1588 of ``lib``.
1589
1590 .. conf::
1591 :keys: env_bin_dir, envbindir
1592 :constant:
1593 :version_added: 0.5
1594
1595 The binary folder where console/gui scripts are generated during installation.
1596
1597 .. conf::
1598 :keys: env_python, envpython
1599 :constant:
1600 :version_added: 0.5
1601
1602 The Python executable from within the tox environment.
1603
1604 .. conf::
1605 :keys: py_dot_ver
1606 :constant:
1607 :version_added: 4.0.10
1608
1609 Major.Minor version of the Python interpreter in the tox environment (e.g., ``3.14``).
1610
1611 .. conf::
1612 :keys: py_impl
1613 :constant:
1614 :version_added: 4.0.10
1615
1616 Name of the Python implementation in the tox environment in lowercase (e.g., ``cpython``, ``pypy``).
1617
1618 .. conf::
1619 :keys: py_free_threaded
1620 :constant:
1621 :version_added: 4.26
1622
1623 ``True`` if the Python interpreter in the tox environment is a free-threaded CPython build,
1624 else ``False``.
1625
1626 Python run
1627 ==========
1628
1629 .. conf::
1630 :keys: dependency_groups
1631 :default: <empty list>
1632 :version_added: 4.22
1633
1634 A list of names of dependency groups (as defined by :pep:`735`) to install into this Python environment. The
1635 installation will happen before installing the package or any of its dependencies.
1636
1637 For example:
1638
1639 .. tab:: TOML
1640
1641 .. code-block:: toml
1642
1643 [dependency-groups]
1644 test = [
1645 "pytest>=8",
1646 ]
1647
1648 [tool.tox.env_run_base]
1649 dependency_groups = [
1650 "test",
1651 ]
1652
1653 .. tab:: INI
1654
1655 .. code-block:: ini
1656
1657 [testenv]
1658 dependency_groups =
1659 test
1660
1661 .. code-block:: toml
1662
1663 [dependency-groups]
1664 test = [
1665 "pytest>=8",
1666 ]
1667
1668 .. conf::
1669 :keys: pylock
1670 :default: <empty string>
1671 :version_added: 4.44
1672
1673 Path to a :pep:`751` ``pylock.toml`` lock file to install locked dependencies from. Mutually exclusive with
1674 :ref:`deps`. Each package in the lock file is filtered by evaluating its environment markers against the target
1675 Python interpreter and the configured :ref:`extras` and :ref:`dependency_groups`, then converted to a pinned
1676 requirement (``name==version``) and installed via pip with ``--no-deps``. The path is resolved relative to the
1677 :ref:`package_root` (or :ref:`tox_root` if no package root is configured). Change detection is automatic: adding,
1678 removing, or changing packages triggers environment recreation as needed. See :ref:`pylock-explanation` for details.
1679
1680 For example:
1681
1682 .. tab:: TOML
1683
1684 .. code-block:: toml
1685
1686 [tool.tox.env_run_base]
1687 pylock = "pylock.toml"
1688
1689 .. tab:: INI
1690
1691 .. code-block:: ini
1692
1693 [testenv]
1694 pylock = pylock.toml
1695
1696 .. conf::
1697 :keys: deps
1698 :default: <empty list>
1699 :version_added: 0.5
1700
1701 Python dependencies. Installed into the environment prior to project after environment creation, but
1702 before package installation. All installer commands are executed using the :ref:`tox_root` as the current working
1703 directory. Each value must be one of:
1704
1705 - a Python dependency as specified by :pep:`440`,
1706 - a `requirement file <https://pip.pypa.io/en/stable/user_guide/#requirements-files>`_ when the value starts with
1707 ``-r`` (followed by a file path or URL),
1708 - a `constraint file <https://pip.pypa.io/en/stable/user_guide/#constraints-files>`_ when the value starts with
1709 ``-c`` (followed by a file path or URL).
1710
1711 If you are only defining :pep:`508` requirements (aka no pip requirement files), you should use
1712 :ref:`dependency_groups` instead.
1713
1714 For example:
1715 .. tab:: TOML
1716
1717 .. code-block:: toml
1718
1719 [tool.tox.env_run_base]
1720 deps = [
1721 "pytest>=8",
1722 "-r requirements.txt",
1723 "-c constraints.txt",
1724 ]
1725
1726 .. tab:: INI
1727
1728 .. code-block:: ini
1729
1730 [testenv]
1731 deps =
1732 pytest>=7,<8
1733 -r requirements.txt
1734 -c constraints.txt
1735
1736 .. note::
1737
1738 :ref:`constraints` is the preferred way to specify constraints files since they will apply to package dependencies
1739 also.
1740
1741 .. conf::
1742 :keys: constraints
1743 :default: <empty list>
1744 :version_added: 4.28.0
1745
1746 `Constraints files <https://pip.pypa.io/en/stable/user_guide/#constraints-files>`_ to use during package and
1747 dependency installation. Provided constraints files will be used when installing package dependencies and any
1748 additional dependencies specified in :ref:`deps`, but will not be used when installing the package itself.
1749 Each value must be a file path or URL.
1750
1751 .. conf::
1752 :keys: use_develop, usedevelop
1753 :default: false
1754 :version_added: 1.6
1755
1756 Install the current package in development mode using :pep:`660`. This means that the package will
1757 be installed in-place and editable.
1758
1759 .. note::
1760
1761 ``package = editable`` is the preferred way to enable development/editable mode. See the details in :ref:`package`.
1762
1763 .. note::
1764
1765 PEP-660 introduced a standardized way of installing a package in development mode, providing the same effect as if
1766 ``pip install -e`` was used.
1767
1768 .. conf::
1769 :keys: package
1770 :version_added: 4.0
1771
1772 When option can be one of ``wheel``, ``sdist``, ``sdist-wheel``, ``editable``, ``editable-legacy``, ``deps-only``,
1773 ``skip``, or ``external``. If :ref:`use_develop` is set this becomes a constant of ``editable``. If
1774 :ref:`skip_install` is set this becomes a constant of ``skip``.
1775
1776 When ``deps-only`` is selected, tox installs the package's dependencies (including any requested :ref:`extras`) but
1777 does **not** build or install the package itself. This is useful for environments that need the same dependencies as
1778 the package without the package, such as coverage combining, documentation building, or linting. For projects with
1779 static :pep:`621` metadata in ``pyproject.toml``, dependencies are read directly without creating a packaging
1780 environment. For dynamic dependencies or non-PEP-621 projects, the packaging environment is used to extract
1781 metadata.
1782
1783 When ``sdist-wheel`` is selected, tox first builds a source distribution and then builds a wheel from that sdist
1784 (rather than directly from the source tree). This is useful for verifying that the sdist is complete and that the
1785 package can be correctly built from it — catching missing files or packaging errors early.
1786
1787 When ``editable`` is selected and the build backend supports :pep:`660`, tox will use the standardized editable
1788 install mechanism. If the backend does not support :pep:`660`, tox will automatically fall back to
1789 ``editable-legacy`` mode (equivalent to ``pip install -e``) and print a message suggesting you make this setting
1790 explicit in your configuration. To ensure your backend supports the standardized method, verify it meets the minimum
1791 version requirement (e.g. ``setuptools>=64``).
1792
1793 .. conf::
1794 :keys: wheel_build_env
1795 :version_added: 4.0
1796 :default: <package_env>-<python-flavor-lowercase><python-version-no-dot>
1797
1798 If :ref:`package` is set to ``wheel`` or ``sdist-wheel`` this will be the tox Python environment in which the wheel
1799 will be built. For ``sdist-wheel``, the sdist is first built in the :ref:`package_env` environment, then the wheel
1800 is built from the extracted sdist in this environment. The value is generated to be unique per Python flavor and
1801 version, and prefixed with :ref:`package_env` value.
1802 This is to ensure the target interpreter and the generated wheel will be compatible. If you have a wheel that can be
1803 reused across multiple Python versions set this value to the same across them (to avoid building a new wheel for
1804 each one of them).
1805
1806 .. conf::
1807 :keys: extras
1808 :version_added: 2.4
1809 :default: <empty list>
1810
1811 A list of "extras" from the package to be installed. For example, ``extras = testing`` is equivalent to ``[testing]``
1812 in a ``pip install`` command.
1813
1814 .. _external-package-builder:
1815
1816 External package builder
1817 ========================
1818
1819 tox supports operating with externally built packages. External packages might be provided in two ways:
1820
1821 - explicitly via the :ref:`--installpkg <tox-run---installpkg>` CLI argument,
1822 - setting the :ref:`package` to ``external`` and using a tox packaging environment named ``<package_env>_external`` (see
1823 :ref:`package_env`) to build the package. The tox packaging environment takes all configuration flags of a
1824 :ref:`python environment <python-options>`, plus the following:
1825
1826 .. conf::
1827 :keys: deps
1828 :default: <empty list>
1829 :ref_suffix: external
1830 :version_added: 0.5
1831
1832 Name of the Python dependencies as specified by :pep:`440`. Installed into the environment prior running the build
1833 commands. All installer commands are executed using the :ref:`tox_root` as the current working directory.
1834
1835 .. conf::
1836 :keys: commands
1837 :default: <empty list>
1838 :ref_suffix: external
1839 :version_added: 0.5
1840
1841 Commands to run that will build the package. If any command fails the packaging operation is considered failed and
1842 will fail all environments using that package.
1843
1844 .. conf::
1845 :keys: ignore_errors
1846 :default: False
1847 :ref_suffix: external
1848 :version_added: 2.0
1849
1850 When executing the commands keep going even if a sub-command exits with non-zero exit code. The overall status will
1851 be "commands failed", i.e. tox will exit non-zero in case any command failed. It may be helpful to note that this
1852 setting is analogous to the ``-k`` or ``--keep-going`` option of GNU Make.
1853
1854 .. conf::
1855 :keys: change_dir, changedir
1856 :default: {tox_root}
1857 :ref_suffix: external
1858 :version_added: 0.5
1859
1860 Change to this working directory when executing the package build command. If the directory does not exist yet, it
1861 will be created (required for Windows to be able to execute any command).
1862
1863 .. conf::
1864 :keys: package_glob
1865 :default: {envtmpdir}{/}dist{/}*
1866 :version_added: 4.0
1867
1868 A glob that should match the wheel/sdist file to install. If no file or multiple files is matched the packaging
1869 operation is considered failed and will raise an error.
1870
1871 Python virtual environment
1872 ==========================
1873
1874 .. conf::
1875 :keys: system_site_packages, sitepackages
1876 :default: False
1877 :version_added: 0.8
1878
1879 Create virtual environments that also have access to globally installed packages. Note the default value may be
1880 overwritten by the ``VIRTUALENV_SYSTEM_SITE_PACKAGES`` environment variable.
1881
1882 .. warning::
1883
1884 In cases where a command line tool is also installed globally you have to make sure that you use the tool installed
1885 in the virtualenv by using ``python -m <command line tool>`` (if supported by the tool) or
1886 ``{env_bin_dir}/<command line tool>``. If you forget to do that you will get an error.
1887
1888 .. conf::
1889 :keys: always_copy, alwayscopy
1890 :default: False
1891 :version_added: 2.6
1892
1893 Force virtualenv to always copy rather than symlink. Note the default value may be overwritten by the
1894 ``VIRTUALENV_COPIES`` or ``VIRTUALENV_ALWAYS_COPY`` (in that order) environment variables. This is useful for
1895 situations where hardlinks don't work (e.g. running in VMS with Windows guests).
1896
1897 .. conf::
1898 :keys: download
1899 :version_added: 3.10
1900 :default: False
1901
1902 True if you want virtualenv to upgrade pip/wheel/setuptools to the latest version. Note the default value may be
1903 overwritten by the ``VIRTUALENV_DOWNLOAD`` environment variable. If (and only if) you want to choose a specific
1904 version (not necessarily the latest) then you can add ``VIRTUALENV_PIP=20.3.3`` (and similar) to your :ref:`set_env`.
1905
1906 .. conf::
1907 :keys: virtualenv_spec
1908 :default: ""
1909 :version_added: 4.42
1910
1911 A :pep:`440` version specifier for virtualenv (e.g. ``virtualenv<20.22.0``). When set, tox bootstraps the specified
1912 virtualenv version into an isolated environment and drives it via subprocess, instead of using the imported
1913 virtualenv library. This enables environments targeting Python versions that are incompatible with the virtualenv
1914 installed alongside tox.
1915
1916 The bootstrap environment is cached under ``.tox/.virtualenv-bootstrap/`` (keyed by a hash of the spec string) and
1917 reused across runs. Concurrent access is protected by a file lock. When the spec is empty (the default), tox uses
1918 the imported virtualenv with zero overhead.
1919
1920 .. tab:: TOML
1921
1922 .. code-block:: toml
1923
1924 [env.legacy]
1925 base_python = ["python3.6"]
1926 virtualenv_spec = "virtualenv<20.22.0"
1927 commands = [["python", "-c", "import sys; print(sys.version)"]]
1928
1929 [env.modern]
1930 base_python = ["python3.15"]
1931 commands = [["python", "-c", "import sys; print(sys.version)"]]
1932
1933 .. tab:: INI
1934
1935 .. code-block:: ini
1936
1937 [testenv:legacy]
1938 base_python = python3.6
1939 virtualenv_spec = virtualenv<20.22.0
1940 commands = python -c 'import sys; print(sys.version)'
1941
1942 [testenv:modern]
1943 base_python = python3.15
1944 commands = python -c 'import sys; print(sys.version)'
1945
1946 Changing this value triggers automatic environment recreation (the spec is included in the cache key).
1947
1948 See :ref:`virtualenv-version-pinning` for background on when and why to use this setting.
1949
1950 Python virtual environment packaging
1951 ====================================
1952
1953 .. conf::
1954 :keys: meta_dir
1955 :version_added: 4.0.0
1956 :default: {env_dir}/.meta
1957
1958 Directory where to put the project metadata files.
1959
1960 .. conf::
1961 :keys: pkg_dir
1962 :version_added: 4.0.0
1963 :default: {env_dir}/.dist
1964
1965 Directory where to put project packages.
1966
1967 .. conf::
1968 :keys: config_settings_get_requires_for_build_sdist
1969 :version_added: 4.11
1970
1971 Config settings (``dict[str, str]``) passed to the ``get_requires_for_build_sdist`` backend API endpoint.
1972
1973 .. conf::
1974 :keys: config_settings_build_sdist
1975 :version_added: 4.11
1976
1977 Config settings (``dict[str, str]``) passed to the ``build_sdist`` backend API endpoint.
1978
1979 .. conf::
1980 :keys: config_settings_get_requires_for_build_wheel
1981 :version_added: 4.11
1982
1983 Config settings (``dict[str, str]``) passed to the ``get_requires_for_build_wheel`` backend API endpoint.
1984
1985 .. conf::
1986 :keys: config_settings_prepare_metadata_for_build_wheel
1987 :version_added: 4.11
1988
1989 Config settings (``dict[str, str]``) passed to the ``prepare_metadata_for_build_wheel`` backend API endpoint.
1990
1991 .. conf::
1992 :keys: config_settings_build_wheel
1993 :version_added: 4.11
1994
1995 Config settings (``dict[str, str]``) passed to the ``build_wheel`` backend API endpoint.
1996
1997 .. conf::
1998 :keys: config_settings_get_requires_for_build_editable
1999 :version_added: 4.11
2000
2001 Config settings (``dict[str, str]``) passed to the ``get_requires_for_build_editable`` backend API endpoint.
2002
2003 .. conf::
2004 :keys: config_settings_prepare_metadata_for_build_editable
2005 :version_added: 4.11
2006
2007 Config settings (``dict[str, str]``) passed to the ``prepare_metadata_for_build_editable`` backend API endpoint.
2008
2009 .. conf::
2010 :keys: config_settings_build_editable
2011 :version_added: 4.11
2012
2013 Config settings (``dict[str, str]``) passed to the ``build_editable`` backend API endpoint.
2014
2015 .. conf::
2016 :keys: fresh_subprocess
2017 :version_added: 4.14.0
2018 :default: True if build backend is setuptools otherwise False
2019
2020 A flag controlling if each call to the build backend should be done in a fresh subprocess or not (especially older
2021 build backends such as ``setuptools`` might require this to discover newly provisioned dependencies).
2022
2023 Pip installer
2024 =============
2025
2026 .. conf::
2027 :keys: install_command
2028 :default: python -I -m pip install {opts} {packages}
2029 :version_added: 1.6
2030
2031 Determines the command used for installing packages into the virtual environment; both the package under test and its
2032 dependencies (defined with :ref:`deps`). Must contain the substitution key ``{packages}`` which will be replaced by
2033 the package(s) to install. You should also accept ``{opts}`` -- it will contain index server options such as
2034 ``--pre`` (configured as ``pip_pre``).
2035
2036 .. note::
2037
2038 You can also provide arbitrary commands to the ``install_command``. Please take care that these commands can be
2039 executed on the supported operating systems. When executing shell scripts we recommend to not specify the script
2040 directly but instead pass it to the appropriate shell as argument (e.g. prefer ``bash script.sh`` over
2041 ``script.sh``).
2042
2043 .. conf::
2044 :keys: list_dependencies_command
2045 :default: python -m pip freeze --all
2046 :version_added: 2.4
2047
2048 The ``list_dependencies_command`` setting is used for listing the packages installed into the virtual environment.
2049 This command will be executed only if executing on Continuous Integrations is detected (for example set environment
2050 variable ``CI=1``) or if journal is active. In TOML configurations, reference this Command value using
2051 ``{replace = "ref"}`` with ``extend = true`` rather than string interpolation.
2052
2053 .. conf::
2054 :keys: pip_pre
2055 :default: false
2056 :version_added: 1.9
2057
2058 If ``true``, adds ``--pre`` to the ``opts`` passed to :ref:`install_command`. This will cause it to install the
2059 latest available pre-release of any dependencies without a specified version. If ``false``, pip will only install
2060 final releases of unpinned dependencies.
2061
2062 .. conf::
2063 :keys: constrain_package_deps
2064 :default: false
2065 :version_added: 4.4.0
2066
2067 If ``constrain_package_deps`` is true, then tox will create and use ``{env_dir}{/}constraints.txt`` when installing
2068 package dependencies during ``install_package_deps`` stage. When this value is set to false, any conflicting package
2069 dependencies will override explicit dependencies and constraints passed to :ref:`deps`.
2070
2071 .. conf::
2072 :keys: use_frozen_constraints
2073 :default: false
2074 :version_added: 4.4.0
2075
2076 When ``use_frozen_constraints`` is true, then tox will use the ``list_dependencies_command`` to enumerate package
2077 versions in order to create ``{env_dir}{/}constraints.txt``. Otherwise the package specifications explicitly listed
2078 under ``deps`` (or in requirements / constraints files referenced in ``deps``) will be used as the constraints. If
2079 ``constrain_package_deps`` is false, then this setting has no effect.
2080
2081 ********************
2082 User configuration
2083 ********************
2084
2085 tox allows creation of user level config-file to modify default values of the CLI commands. It is located in the
2086 OS-specific user config directory under ``tox/config.ini`` path, see ``tox --help`` output for exact location. It can be
2087 changed via ``TOX_USER_CONFIG_FILE`` environment variable. Example configuration:
2088
2089 .. code-block:: ini
2090
2091 [tox]
2092 skip_missing_interpreters = true
2093
2094 *****************************************
2095 Set CLI flags via environment variables
2096 *****************************************
2097
2098 All configuration can be overridden via environment variables too, the naming convention here is ``TOX_<option>``. E.g.
2099 ``TOX_WORK_DIR`` sets the ``--workdir`` flag, or ``TOX_OVERRIDE`` sets the ``--override`` flag. For flags accepting more
2100 than one argument, use the ``;`` character to separate these values:
2101
2102 All configuration inside the configuration file may be overwritten via the ``TOX_OVERRIDE``, note in this case the
2103 configuration file and its access (section/table + key) are needed. Here we demonstrate with a ``tox.ini`` file:
2104
2105 .. code-block:: bash
2106
2107 # set FOO and bar as passed environment variable
2108 $ env 'TOX_OVERRIDE=testenv.pass_env=FOO,BAR' tox c -k pass_env -e py
2109 [testenv:py]
2110 pass_env =
2111 BAR
2112 FOO
2113 <default pass_envs>
2114
2115 .. code-block:: bash
2116
2117 # append FOO and bar as passed environment variable to the list already defined in
2118 # the tox configuration
2119 $ env 'TOX_OVERRIDE=testenv.pass_env+=FOO,BAR' tox c -k pass_env -e py
2120 [testenv:py]
2121 pass_env =
2122 BAR
2123 FOO
2124 <pass_envs defined in configuration>
2125 <default pass_envs>
2126
2127 .. code-block:: bash
2128
2129 # set httpx and deps to and 3.12 as base_python
2130 $ env 'TOX_OVERRIDE=testenv.deps=httpx;testenv.base_python=3.12' .tox/dev/bin/tox c \
2131 -k deps base_python -e py
2132 [testenv:py]
2133 deps = httpx
2134 base_python = 3.12
2135
2136 ************************************************
2137 Overriding configuration from the command line
2138 ************************************************
2139
2140 You can override options in the configuration file, from the command line. For example, given this config:
2141
2142 .. tab:: TOML
2143
2144 .. code-block:: toml
2145
2146 # tox.toml
2147 [env_run_base]
2148 deps = ["pytest"]
2149 set_env = { foo = "bar" }
2150 commands = [[ "pytest", "tests" ]]
2151
2152 .. tab:: INI
2153
2154 .. code-block:: ini
2155
2156 [testenv]
2157 deps = pytest
2158 set_env =
2159 foo=bar
2160 commands = pytest tests
2161
2162 You could enable ``ignore_errors`` by running:
2163
2164 .. tab:: TOML
2165
2166 .. code-block:: bash
2167
2168 tox --override env_run_base.ignore_errors=True
2169
2170 .. tab:: INI
2171
2172 .. code-block:: bash
2173
2174 tox --override testenv.ignore_errors=True
2175
2176 You could add additional dependencies by running:
2177
2178 .. tab:: TOML
2179
2180 .. code-block:: bash
2181
2182 tox --override env_run_base.deps+=pytest-xdist
2183
2184 .. tab:: INI
2185
2186 .. code-block:: bash
2187
2188 tox --override testenv.deps+=pytest-xdist
2189
2190 You could set additional environment variables by running:
2191
2192 .. tab:: TOML
2193
2194 .. code-block:: bash
2195
2196 tox --override env_run_base.set_env+=baz=quux
2197
2198 .. tab:: INI
2199
2200 .. code-block:: bash
2201
2202 tox --override testenv.set_env+=baz=quux
2203
2204 You can specify overrides multiple times on the command line to append multiple items:
2205
2206 .. tab:: TOML
2207
2208 .. code-block:: bash
2209
2210 tox -x env_run_base.set_env+=foo=bar -x env_run_base.set_env+=baz=quux
2211 tox -x testenv_run_baseenv.deps+=pytest-xdist -x env_run_base.deps+=pytest-covt
2212
2213 .. tab:: INI
2214
2215 .. code-block:: bash
2216
2217 tox -x testenv.set_env+=foo=bar -x testenv.set_env+=baz=quux
2218 tox -x testenv.deps+=pytest-xdist -x testenv.deps+=pytest-covt
2219
2220 Or reset override and append to that (note the first override is ``=`` and not ``+=``):
2221
2222 .. tab:: TOML
2223
2224 .. code-block:: bash
2225
2226 tox -x env_run_base.deps=pytest-xdist -x env_run_base.deps+=pytest-cov
2227
2228 .. tab:: INI
2229
2230 .. code-block:: bash
2231
2232 tox -x testenv.deps=pytest-xdist -x testenv.deps+=pytest-cov
2233
2234 Escaping dots in override keys
2235 ==============================
2236
2237 .. versionadded:: 4.52
2238
2239 Environment names can contain literal dots (e.g., ``py3.14``). Since ``.`` is also the separator between namespace
2240 components and the config key, you need to escape literal dots with a backslash (``\.``) so they are not treated as
2241 separators:
2242
2243 .. tab:: TOML
2244
2245 .. code-block:: bash
2246
2247 tox -x 'env.3\.14.deps=pytest-xdist'
2248
2249 .. tab:: INI
2250
2251 .. code-block:: bash
2252
2253 tox -x 'testenv:3\.14.deps=pytest-xdist'
2254
2255 Multiple dots can be escaped in the same key: ``-x 'some\.dotted\.name.key=val'``. A backslash not followed by a dot
2256 passes through literally.
2257
2258 ***********
2259 TOML only
2260 ***********
2261
2262 These additional rules are active for native TOML configuration files.
2263
2264 String elements (excluding keys) will be transformed according to the :ref:`Substitutions <substitution>` section.
2265
2266 String substitution references
2267 ==============================
2268
2269 .. versionadded:: 4.21
2270
2271 Within strings values from other sections can be referred to via ``{[<table>]<key>}``:
2272
2273 which you can use to avoid repetition of config values. You can put default values in one section and reference them in
2274 others to avoid repeating the same values:
2275
2276 .. code-block:: toml
2277
2278 [extra]
2279 ok = "o"
2280 [.env.B]
2281 description = "{[extra]ok}"
2282
2283 If the target table is one of the tox environments variable substitution will be applied on the replaced value,
2284 otherwise the text will be inserted as is (e.g., here with extra).
2285
2286 Configuration reference
2287 =======================
2288
2289 .. versionadded:: 4.21
2290
2291 You can reference other configurations via the ``ref`` replacement. This can either be of type:
2292
2293 - ``env``, in this case the configuration is loaded from another tox environment, where string substitution will happen
2294 in that environments scope:
2295
2296 .. code-block:: toml
2297
2298 [env.src]
2299 extras = ["A", "{env_name}"]
2300 [env.dest]
2301 extras = [{ replace = "ref", env = "src", key = "extras", extend = true }, "B"]
2302
2303 In this case ``dest`` environments ``extras`` will be ``A``, ``src``, ``B``.
2304
2305 - ``raw``, in this case the configuration is loaded as raw, and substitution executed in the current environments scope:
2306
2307 .. code-block:: toml
2308
2309 [env.src]
2310 extras = ["A", "{env_name}"]
2311 [env.dest]
2312 extras = [{ replace = "ref", of = ["env", "src", "extras"], extend = true }, "B"]
2313
2314 In this case ``dest`` environments ``extras`` will be ``A``, ``dest``, ``B``.
2315
2316 The ``extend`` flag controls if after replacement the value should be replaced as is in the host structure (when flag is
2317 false -- by default) or be extended into. This flag only operates when the host is a list.
2318
2319 When referencing Command-type configuration values (like ``list_dependencies_command``), the reference automatically
2320 extracts the command's argument list, making it compatible with TOML's structured ``commands`` format. For example:
2321
2322 .. code-block:: toml
2323
2324 [tool.tox.env.a]
2325 package = "skip"
2326 commands = [[{ replace = "ref", env = "a", key = "list_dependencies_command", extend = true }]]
2327
2328 This expands the Command's args into the command list, avoiding the need for string interpolation which doesn't work
2329 properly with Command values in TOML.
2330
2331 Positional argument reference
2332 =============================
2333
2334 .. versionadded:: 4.21
2335
2336 You can reference positional arguments via the ``posargs`` replacement:
2337
2338 .. code-block:: toml
2339
2340 [env.A]
2341 commands = [["python", { replace = "posargs", default = ["a", "b"], extend = true } ]]
2342
2343 If the positional arguments are not set commands will become ``python a b``, otherwise will be ``python posarg-set``.
2344 The ``extend`` option instructs tox to unroll the positional arguments within the host structure. Without it the result
2345 would become ``["python", ["a", "b"]`` which would be invalid.
2346
2347 Note that:
2348
2349 .. code-block:: toml
2350
2351 [env.A]
2352 commands = [["python", "{posargs}" ]]
2353
2354 Differs in sense that the positional arguments will be set as a single argument, while in the original example they are
2355 passed through as separate.
2356
2357 Empty commands groups will be ignored:
2358
2359 .. code-block:: toml
2360
2361 [env.A]
2362 commands = [[], ["pytest"]]
2363
2364 will only invoke pytest. This is especially useful together with posargs allowing you to opt out of running a set of
2365 commands:
2366
2367 .. code-block:: toml
2368
2369 [env.A]
2370 commands = [
2371 { replace = "posargs", default = ["python", "patch.py"]},
2372 ["pytest"]
2373 ]
2374
2375 When running ``tox run -e A`` it will invoke ``python patch.py`` followed by pytest. When running ``tox run -e A --`` it
2376 will invoke only pytest.
2377
2378 Environment variable reference
2379 ==============================
2380
2381 .. versionadded:: 4.21
2382
2383 You can reference environment variables via the ``env`` replacement:
2384
2385 .. code-block:: toml
2386
2387 [env.A]
2388 set_env.COVERAGE_FILE = { replace = "env", name = "COVERAGE_FILE", default = "ok" }
2389
2390 If the environment variable is set the the ``COVERAGE_FILE`` will become that, otherwise will default to ``ok``.
2391
2392 References within set_env
2393 =========================
2394
2395 .. versionadded:: 4.21.1
2396
2397 When you want to inherit ``set_env`` from another environment you can use the feature that if you pass a list of
2398 dictionaries to ``set_env`` they will be merged together, for example:
2399
2400 .. code-block:: toml
2401
2402 [tool.tox.env_run_base]
2403 set_env = { A = "1", B = "2"}
2404
2405 [tool.tox.env.magic]
2406 set_env = [
2407 { replace = "ref", of = ["tool", "tox", "env_run_base", "set_env"]},
2408 { C = "3", D = "4"},
2409 ]
2410
2411 Here the ``magic`` tox environment will have both ``A``, ``B``, ``C`` and ``D`` environments set.
2412
2413 Glob pattern reference
2414 ======================
2415
2416 .. versionadded:: 4.40
2417
2418 You can expand file system glob patterns via the ``glob`` replacement. Matched paths are sorted for deterministic
2419 output, and relative patterns are resolved against ``tox_root``. The ``**`` wildcard matches any number of directories
2420 recursively.
2421
2422 .. code-block:: toml
2423
2424 [env.A]
2425 commands = [["twine", "upload", { replace = "glob", pattern = "dist/*.whl", extend = true }]]
2426
2427 When used with ``extend = true`` the matched files are expanded as separate arguments in the host list. Without
2428 ``extend`` the matches are joined as a single space-separated string.
2429
2430 If no files match and a ``default`` is provided it will be used as fallback:
2431
2432 .. code-block:: toml
2433
2434 [env.A]
2435 commands = [["twine", "upload", { replace = "glob", pattern = "dist/*.whl", default = ["fallback.whl"], extend = true }]]
2436
2437 When no files match and no default is given, the result is an empty string (or empty list with ``extend``).
2438
2439 .. _conditional-value-reference:
2440
2441 Conditional value reference
2442 ===========================
2443
2444 .. versionadded:: 4.40 Conditional value replacement with ``env.VAR`` lookups.
2445
2446 .. versionchanged:: 4.42 Added ``factor.NAME`` lookups for environment name factors and platform.
2447
2448 .. versionchanged:: 4.50 Added ``factor['NAME']`` and ``env['VAR']`` subscript syntax and ``env_name`` variable.
2449
2450 You can conditionally select values based on environment variables and factors via the ``if`` replacement. The
2451 ``condition`` field accepts an expression language that supports ``env.VAR_NAME`` lookups for environment variables,
2452 ``factor.NAME`` lookups for environment name factors and platform, ``==``/``!=`` comparisons, and ``and``/``or``/``not``
2453 boolean logic.
2454
2455 **Check if an environment variable is set (non-empty):**
2456
2457 .. code-block:: toml
2458
2459 [env.A]
2460 set_env.MATURITY = { replace = "if", condition = "env.TAG_NAME", then = "production", "else" = "testing" }
2461
2462 If ``TAG_NAME`` is set and non-empty, ``MATURITY`` becomes ``production``, otherwise ``testing``.
2463
2464 **Compare an environment variable to a value:**
2465
2466 .. code-block:: toml
2467
2468 [env.A]
2469 set_env.MODE = { replace = "if", condition = "env.CI == 'true'", then = "ci", "else" = "local" }
2470
2471 **Combine conditions with boolean logic:**
2472
2473 .. code-block:: toml
2474
2475 [env.A]
2476 set_env.DEPLOY_TARGET = { replace = "if", condition = "env.CI and env.DEPLOY", then = "production", "else" = "none" }
2477
2478 [env.B]
2479 pass_env = [{ replace = "if", condition = "env.CI or env.LOCAL", then = ["AWS_*"], "else" = [], extend = true }]
2480
2481 [env.C]
2482 commands = [["pytest", { replace = "if", condition = "not env.CI", then = ["--pdb"], "else" = [], extend = true }]]
2483
2484 [env.D]
2485 set_env.LOG_LEVEL = { replace = "if", condition = "env.MODE != 'prod'", then = "DEBUG", "else" = "INFO" }
2486
2487 **Omitting the else clause** defaults to an empty string:
2488
2489 .. code-block:: toml
2490
2491 [env.A]
2492 set_env.DEPLOY_FLAG = { replace = "if", condition = "env.DEPLOY", then = "1" }
2493
2494 **Nested substitutions** in ``then``/``else`` values are processed normally:
2495
2496 .. code-block:: toml
2497
2498 [env.A]
2499 set_env.TEST_ENV = { replace = "if", condition = "env.DEPLOY", then = "{env_name}", "else" = "local" }
2500
2501 **With extend in list contexts:**
2502
2503 .. code-block:: toml
2504
2505 [env.A]
2506 commands = [["pytest", { replace = "if", condition = "env.VERBOSE", then = ["--verbose", "--debug"], "else" = ["--quiet"], extend = true }]]
2507
2508 **Check if a factor is present:**
2509
2510 .. code-block:: toml
2511
2512 [env_run_base]
2513 deps = [
2514 "pytest",
2515 { replace = "if", condition = "factor.django50", then = ["Django>=5.0,<5.1"], extend = true },
2516 ]
2517
2518 If the environment name contains ``django50`` (e.g., ``py313-django50``), the Django dependency is added.
2519
2520 **Check for platform factors:**
2521
2522 .. code-block:: toml
2523
2524 [env_run_base]
2525 commands = [
2526 { replace = "if", condition = "factor.linux", then = [["pytest", "--numprocesses=auto"]], extend = true },
2527 { replace = "if", condition = "not factor.linux", then = [["pytest"]], extend = true },
2528 ]
2529
2530 The current platform (``sys.platform`` value like ``linux``, ``darwin``, ``win32``) is automatically available as a
2531 factor without requiring it in the environment name.
2532
2533 **Combine factor conditions with environment variables:**
2534
2535 .. code-block:: toml
2536
2537 [env_run_base]
2538 commands = [["pytest", { replace = "if", condition = "factor.linux and env.CI", then = ["--numprocesses=auto"], "else" = [], extend = true }]]
2539
2540 **Check factors with non-identifier names:**
2541
2542 Factor names like ``3.14`` are not valid Python identifiers, so ``factor.3.14`` would be a syntax error. Use subscript
2543 syntax instead:
2544
2545 .. code-block:: toml
2546
2547 [env."test-3.14"]
2548 commands = [
2549 ["pytest", { replace = "if", condition = "factor['3.14']", then = ["--strict-markers"], "else" = [], extend = true }],
2550 ]
2551
2552 In this example, the environment name ``test-3.14`` has factors ``test`` and ``3.14``. The subscript syntax also works
2553 for environment variables: ``env['CI']`` is equivalent to ``env.CI``.
2554
2555 **Check the environment name:**
2556
2557 Use ``env_name`` to match the full environment name as a string:
2558
2559 .. code-block:: toml
2560
2561 [env_run_base]
2562 set_env.CUSTOM_FLAG = { replace = "if", condition = "env_name == 'test-3.14'", then = "enabled", "else" = "" }
2563
2564 **Condition expression reference:**
2565
2566 - ``env.VAR`` -- value of environment variable ``VAR`` (empty string if unset); truthy when non-empty
2567 - ``env['VAR']`` -- same as ``env.VAR``
2568 - ``factor.NAME`` -- ``True`` if ``NAME`` is a factor in the environment name or platform; ``False`` otherwise
2569 - ``factor['NAME']`` -- same as ``factor.NAME``, for names that aren't valid Python identifiers (e.g. ``3.14``)
2570 - ``env_name`` -- the full environment name as a string
2571 - ``==``, ``!=`` -- string comparison
2572 - ``and``, ``or``, ``not`` -- boolean logic
2573 - ``'string'`` -- string literal
2574
2575 **********
2576 INI only
2577 **********
2578
2579 These additional rules are active for native INI configuration.
2580
2581 The value for each setting in an INI configuration will be transformed according to the :ref:`Substitutions
2582 <substitution>` section.
2583
2584 Substitution for values from other sections
2585 ===========================================
2586
2587 .. versionadded:: 1.4
2588
2589 Values from other sections can be referred to via:
2590
2591 ::
2592
2593 {[sectionname]valuename}
2594
2595 which you can use to avoid repetition of config values. You can put default values in one section and reference them in
2596 others to avoid repeating the same values:
2597
2598 .. code-block:: ini
2599
2600 [base]
2601 deps =
2602 pytest
2603 mock
2604 pytest-xdist
2605
2606 [testenv:dulwich]
2607 deps =
2608 dulwich
2609 {[base]deps}
2610
2611 [testenv:mercurial]
2612 deps =
2613 mercurial
2614 {[base]deps}
2615
2616 .. _conditional-settings:
2617
2618 Conditional settings
2619 ====================
2620
2621 - Configurations may be set conditionally within the ``tox.ini`` file. If a line starts with an environment name or
2622 names, separated by a comma, followed by ``:`` the configuration will only be used if the environment name(s) matches
2623 the executed tox environment. For example:
2624
2625 .. code-block:: ini
2626
2627 [testenv]
2628 deps =
2629 pip
2630 format: black
2631 py310,py39: pytest
2632
2633 Here pip will be always installed as the configuration value is not conditional. black is only used for the ``format``
2634 environment, while ``pytest`` is only installed for the ``3.10`` and ``3.9`` environments.
2635
2636 - **Negative factors**: prefixing a factor name with ``!`` inverts the match -- the line is included only when the
2637 factor is *not* present in the environment name:
2638
2639 .. code-block:: ini
2640
2641 [testenv]
2642 deps =
2643 !lint: pytest
2644 !lint: coverage
2645 lint: ruff
2646
2647 Here ``pytest`` and ``coverage`` are installed for every environment *except* ``lint``, while ``ruff`` is only
2648 installed for ``lint``.
2649
2650 - **Multi-factor conditions with negation**: you can combine positive and negative factors:
2651
2652 .. code-block:: ini
2653
2654 [testenv]
2655 deps =
2656 # installed only when both "django" and "mysql" factors are present
2657 django-mysql: PyMySQL
2658 # installed for all envs except those with the "slow" factor
2659 !slow: pytest-timeout
2660 # installed when either "3.12" or "3.13" factor is present, but not "minimal"
2661 !minimal-3.12,!minimal-3.13: hypothesis
2662
2663 - **Factor-conditional commands**: factor conditions work in any multi-line setting, not just ``deps``:
2664
2665 .. code-block:: ini
2666
2667 [testenv]
2668 commands =
2669 pytest tests
2670 coverage: coverage report --fail-under=80
2671
2672 The ``coverage report`` command only runs in environments whose name contains the ``coverage`` factor (e.g.
2673 ``3.13-coverage``).
2674
2675 - **Default fallback**: when *all* lines in a setting are conditional and none match the current environment, the
2676 setting falls back to its default value. For example:
2677
2678 .. code-block:: ini
2679
2680 [testenv]
2681 base_python =
2682 py312: python3.12
2683 py313: python3.13
2684
2685 If you run an environment named ``lint`` (which contains neither the ``py312`` nor ``py313`` factor), ``base_python``
2686 falls back to the default -- derived from the environment name -- rather than becoming an empty string. This applies
2687 to any configuration key, not just ``base_python``.
2688
2689 .. _generative-environment-list:
2690
2691 Generative environment list
2692 ===========================
2693
2694 If you have a large matrix of dependencies, python versions and/or environments you can use a generative :ref:`env_list`
2695 and conditional settings to express that in a concise form:
2696
2697 .. tab:: TOML
2698
2699 .. code-block:: toml
2700
2701 env_list = [
2702 "lint",
2703 { product = [
2704 { prefix = "py3", start = 9, stop = 11 },
2705 ["django41", "django40"],
2706 ["sqlite", "mysql"],
2707 ] },
2708 ]
2709
2710 [env_run_base]
2711 deps = [
2712 { replace = "if", condition = "factor.django41", then = ["Django>=4.1,<4.2"], extend = true },
2713 { replace = "if", condition = "factor.django40", then = ["Django>=4.0,<4.1"], extend = true },
2714 { replace = "if", condition = "factor.py311 and factor.mysql", then = ["PyMySQL"], extend = true },
2715 { replace = "if", condition = "factor.py311 or factor.py310", then = ["urllib3"], extend = true },
2716 { replace = "if", condition = "(factor.py311 or factor.py310) and factor.sqlite", then = ["mock"], extend = true },
2717 ]
2718
2719 .. tab:: INI
2720
2721 .. code-block:: ini
2722
2723 [tox]
2724 env_list = py3{9-11}-django{41,40}-{sqlite,mysql}
2725
2726 [testenv]
2727 deps =
2728 django41: Django>=4.1,<4.2
2729 django40: Django>=4.0,<4.1
2730 py311-mysql: PyMySQL
2731 py311,py310: urllib3
2732 py{311,310}-sqlite: mock
2733
2734 This will generate the following tox environments (plus ``lint``):
2735
2736 .. code-block:: shell
2737
2738 > tox l
2739 default environments:
2740 py39-django41-sqlite -> [no description]
2741 py39-django41-mysql -> [no description]
2742 py39-django40-sqlite -> [no description]
2743 py39-django40-mysql -> [no description]
2744 py310-django41-sqlite -> [no description]
2745 py310-django41-mysql -> [no description]
2746 py310-django40-sqlite -> [no description]
2747 py310-django40-mysql -> [no description]
2748 py311-django41-sqlite -> [no description]
2749 py311-django41-mysql -> [no description]
2750 py311-django40-sqlite -> [no description]
2751 py311-django40-mysql -> [no description]
2752
2753 INI expansion syntax
2754 --------------------
2755
2756 Both enumerations (``{1,2,3}``) and numerical ranges (``{1-3}``) are supported, and can be mixed together:
2757
2758 .. code-block:: ini
2759
2760 [tox]
2761 env_list = py3{8-10, 11, 13-14}
2762
2763 [testenv]
2764 deps =
2765 py{310,311-314}: urllib3
2766 setenv =
2767 py{310,311-314}: FOO=bar
2768
2769 will create the following envs:
2770
2771 .. code-block:: shell
2772
2773 > tox l
2774 default environments:
2775 py38 -> [no description]
2776 py39 -> [no description]
2777 py310 -> [no description]
2778 py311 -> [no description]
2779 py313 -> [no description]
2780 py314 -> [no description]
2781
2782 Negative ranges will also be expanded (``{3-1}`` -> ``{3,2,1}``). Non-numerical open ranges such as ``{a-}`` and
2783 ``{-b}`` will not be expanded.
2784
2785 Open-ended numerical ranges use bounds derived from the `supported CPython versions
2786 <https://devguide.python.org/versions/>`_ at the time of the tox release:
2787
2788 - ``{10-}`` expands up to the latest supported CPython minor version (currently **14**)
2789 - ``{-13}`` expands down from the oldest supported CPython minor version (currently **10**)
2790
2791 For example, ``py3{10-}`` is equivalent to ``py3{10,11,12,13,14}`` and ``py3{-13}`` is equivalent to
2792 ``py3{10,11,12,13}``. These bounds are updated with each tox release as new CPython versions become supported or old
2793 ones reach end-of-life.
2794
2795 .. caution::
2796
2797 Be conscious of the number of significant digits in your range endpoints. A range like ``py{39-314}`` will not do
2798 what you may expect. (It expands to 275 environment names, ``py39``, ``py40``, ``py41`` … ``py314``.) Instead, use
2799 ``py3{9-14}``.
2800
2801 TOML ``env_list`` item shapes
2802 -----------------------------
2803
2804 TOML replaces INI's curly-brace expansion with four structured item shapes. Composition happens through these dicts only
2805 — TOML never interprets ``{...}`` inside a string item, so a literal ``"3.{12-14}"`` is the env name ``3.{12-14}``, not
2806 a range.
2807
2808 **Literal string** -- a single environment name.
2809
2810 .. code-block:: toml
2811
2812 env_list = ["lint", "3.12"]
2813
2814 **Bare range dict** -- a single range axis. Accepts ``prefix``, ``start``, and ``stop``. Omit ``stop`` to expand up to
2815 the latest supported CPython minor version (currently **14**), or omit ``start`` to expand down from the oldest
2816 (currently **10**). The bare range dict is equivalent to a single-group ``product`` and is the preferred spelling when
2817 there is only one axis:
2818
2819 .. code-block:: toml
2820
2821 env_list = [
2822 { prefix = "3.", start = 10 },
2823 "lint",
2824 ]
2825
2826 ``{ prefix = "3.", start = 10 }`` is equivalent to ``3.{10-}`` in INI.
2827
2828 **Bare labeled dict** -- a single-key dict mapping a label to a list of factor values. The label also registers for
2829 ``{factor:label}`` substitution (see :ref:`factor-label-substitution`):
2830
2831 .. code-block:: toml
2832
2833 env_list = [
2834 { ecosystem = ["oci", "python"] },
2835 ]
2836
2837 **Product dict** -- a Cartesian product of multiple factor groups, joined with ``-``. Each factor group inside
2838 ``product`` is itself an array of strings, a range dict, or a labeled dict:
2839
2840 .. code-block:: toml
2841
2842 env_list = [
2843 { product = [{ prefix = "3.", start = 12, stop = 14 }, ["django42", "django50"]] },
2844 ]
2845
2846 An ``exclude`` key removes specific combinations from the product -- a capability not available in INI:
2847
2848 .. code-block:: toml
2849
2850 env_list = [
2851 { product = [["3.12", "3.13"], ["django42", "django50"]], exclude = ["3.12-django50"] },
2852 ]
2853
2854 **Common mistake** -- wrapping a range or labeled dict inside a list factor group. Factor-group lists may only contain
2855 literal strings; range and labeled dicts must appear as sibling entries in the ``product`` array, not nested inside one
2856 of its arrays. The following is rejected with a clear error:
2857
2858 .. code-block:: text
2859
2860 # wrong — the inner list contains a dict
2861 env_list = [
2862 { product = [["min"], [{ prefix = "3.", start = 9, stop = 14 }]] },
2863 ]
2864
2865 # right — the range dict is a sibling factor group
2866 env_list = [
2867 { product = [["min"], { prefix = "3.", start = 9, stop = 14 }] },
2868 ]
2869
2870 Generative section names
2871 ========================
2872
2873 Suppose you have some binary packages, and need to run tests both in 32 and 64 bits. You also want an environment to
2874 create your virtual env for the developers. This also supports ranges in the same way as generative environment lists.
2875
2876 .. tab:: INI
2877
2878 .. code-block:: ini
2879
2880 [testenv]
2881 base_python =
2882 py311-x86: python3.11-32
2883 py311-x64: python3.11-64
2884 commands = pytest
2885
2886 [testenv:py311-{x86,x64}-venv]
2887 envdir =
2888 x86: .venv-x86
2889 x64: .venv-x64
2890
2891 .. code-block:: shell
2892
2893 > tox l
2894 default environments:
2895 py -> [no description]
2896
2897 additional environments:
2898 py311-x86-venv -> [no description]
2899 py311-x64-venv -> [no description]
2900
2901 .. tab:: TOML
2902
2903 TOML does not support generative section names. Use :ref:`env_base <env-base-templates>` templates instead:
2904
2905 .. code-block:: toml
2906
2907 [env_base.py311-venv]
2908 factors = [["x86", "x64"]]
2909 base_python = { replace = "if", condition = "factor.x86", then = "python3.11-32", "else" = "python3.11-64" }
2910 env_dir = { replace = "if", condition = "factor.x86", then = ".venv-x86", "else" = ".venv-x64" }
2911 commands = [["pytest"]]
2912
2913 This generates ``py311-venv-x86`` and ``py311-venv-x64``, equivalent to the INI generative section.
2914
2915 .. _substitution:
2916
2917 ***************
2918 Substitutions
2919 ***************
2920
2921 **Value substitution** operates through the ``{...}`` string-substitution pattern. The string inside the curly braces
2922 may reference a global or per-environment config key as described above.
2923
2924 In substitutions, the backslash character ``\`` will act as an escape when preceding ``{``, ``}``, ``:``, ``[``, or
2925 ``]``, otherwise the backslash will be reproduced literally:
2926
2927 .. tab:: TOML
2928
2929 .. code-block:: toml
2930
2931 commands = [
2932 ["python", "-c", 'print("\{posargs} = \{}".format("{posargs}"))'],
2933 ["python", "-c", 'print("host: \{}".format("{env:HOSTNAME:host\: not set}")'],
2934 ]
2935
2936 .. tab:: INI
2937
2938 .. code-block:: ini
2939
2940 commands =
2941 python -c 'print("\{posargs} = \{}".format("{posargs}"))'
2942 python -c 'print("host: \{}".format("{env:HOSTNAME:host\: not set}")'
2943
2944 Note that any backslashes remaining after substitution may be processed by ``shlex`` during command parsing. On POSIX
2945 platforms, the backslash will escape any following character; on windows, the backslash will escape any following quote,
2946 whitespace, or backslash character (since it normally acts as a path delimiter).
2947
2948 Special substitutions that accept additional colon-delimited ``:`` parameters cannot have a space after the ``:`` at the
2949 beginning of line (e.g. ``{posargs: magic}`` would be parsed as factorial ``{posargs``, having value magic).
2950
2951 .. _environment variable substitutions:
2952
2953 Environment variable substitutions
2954 ==================================
2955
2956 If you specify a substitution string like this:
2957
2958 ::
2959
2960 {env:KEY}
2961
2962 then the value will be retrieved as ``os.environ['KEY']`` and replaced with an empty string if the environment variable
2963 does not exist.
2964
2965 Environment variable substitutions with default values
2966 ======================================================
2967
2968 If you specify a substitution string like this:
2969
2970 ::
2971
2972 {env:KEY:DEFAULTVALUE}
2973
2974 then the value will be retrieved as ``os.environ['KEY']`` and replaced with DEFAULTVALUE if the environment variable
2975 does not exist.
2976
2977 If you specify a substitution string like this:
2978
2979 ::
2980
2981 {env:KEY:}
2982
2983 then the value will be retrieved as ``os.environ['KEY']`` and replaced with an empty string if the environment variable
2984 does not exist.
2985
2986 Substitutions can also be nested. In that case they are expanded starting from the innermost expression:
2987
2988 ::
2989
2990 {env:KEY:{env:DEFAULT_OF_KEY}}
2991
2992 the above example is roughly equivalent to ``os.environ.get('KEY', os.environ['DEFAULT_OF_KEY'])``
2993
2994 Interactive shell substitution
2995 ==============================
2996
2997 .. versionadded:: 3.4.0
2998
2999 It's possible to inject a config value only when tox is running in interactive shell (standard input):
3000
3001 ::
3002
3003 {tty:ON_VALUE:OFF_VALUE}
3004
3005 The first value is the value to inject when the interactive terminal is available, the second value is the value to use
3006 when it's not (optional). A good use case for this is e.g. passing in the ``--pdb`` flag for pytest.
3007
3008 .. _command positional substitution:
3009
3010 .. _positional substitution:
3011
3012 Substitutions for positional arguments in commands
3013 ==================================================
3014
3015 .. versionadded:: 1.0
3016
3017 If you specify a substitution string like this:
3018
3019 ::
3020
3021 {posargs:DEFAULTS}
3022
3023 then the value will be replaced with positional arguments as provided to the tox command:
3024
3025 ::
3026
3027 tox arg1 arg2
3028
3029 In this instance, the positional argument portion will be replaced with ``arg1 arg2``. If no positional arguments were
3030 specified, the value of DEFAULTS will be used instead. If DEFAULTS contains other substitution strings, such as
3031 ``{env:*}``, they will be interpreted.,
3032
3033 Use a double ``--`` if you also want to pass options to an underlying test command, for example:
3034
3035 ::
3036
3037 tox run -e 3.14 -- --opt1 ARG1
3038
3039 will make the ``--opt1 ARG1`` appear in all test commands where ``[]`` or ``{posargs}`` was specified. By default (see
3040 ``args_are_paths`` setting), ``tox`` rewrites each positional argument if it is a relative path and exists on the
3041 filesystem to become a path relative to the ``changedir`` setting.
3042
3043 .. _glob substitution:
3044
3045 Glob pattern substitution
3046 =========================
3047
3048 .. versionadded:: 4.40
3049
3050 You can expand glob/wildcard patterns to matching file paths:
3051
3052 ::
3053
3054 {glob:PATTERN}
3055
3056 Matches are sorted and returned as a space-separated string. If no files match, the result is an empty string. You can
3057 provide a default value for when no files match:
3058
3059 ::
3060
3061 {glob:PATTERN:DEFAULT}
3062
3063 Relative patterns are resolved against ``tox_root``. Use ``**`` for recursive matching across directories.
3064
3065 .. tab:: TOML
3066
3067 .. code-block:: toml
3068
3069 [env.A]
3070 commands = [["twine", "upload", "{glob:dist/*.whl}"]]
3071
3072 Or using the TOML dict syntax (see :ref:`pyproject-toml-native`):
3073
3074 .. code-block:: toml
3075
3076 [env.A]
3077 commands = [["twine", "upload", { replace = "glob", pattern = "dist/*.whl", extend = true }]]
3078
3079 .. tab:: INI
3080
3081 .. code-block:: ini
3082
3083 [testenv]
3084 commands = twine upload {glob:dist/*.whl}
3085 deps = {glob:requirements/*.txt:requirements.txt}
3086
3087 Other substitutions
3088 ===================
3089
3090 - ``{:}`` -- replaced with ``os.pathsep`` (``:`` on POSIX, ``;`` on Windows). Useful for building ``PATH``-like values:
3091 ``set_env = PYTHONPATH={tox_root}/src{:}{tox_root}/lib``.
3092 - ``{/}`` -- replaced with ``os.sep`` (``/`` on POSIX, ``\`` on Windows). Useful for cross-platform paths: ``commands =
3093 pytest {tox_root}{/}tests{/}unit``.
3094
3095 .. _substitution-reference:
3096
3097 Substitution quick reference
3098 ============================
3099
3100 The following table lists all available substitution variables. These can be used as inline replacement objects in TOML
3101 or via ``{name}`` in INI.
3102
3103 .. list-table::
3104 :widths: 30 70
3105 :header-rows: 1
3106
3107 - - Substitution
3108 - Description
3109 - - ``{tox_root}`` / ``{toxinidir}``
3110 - The directory where the configuration file is located (project root).
3111 - - ``{work_dir}`` / ``{toxworkdir}``
3112 - The tox working directory (default: ``{tox_root}/.tox``).
3113 - - ``{temp_dir}``
3114 - Temporary directory for tox (default: ``{work_dir}/.tmp``).
3115 - - ``{env_name}`` / ``{envname}``
3116 - Name of the current tox environment (e.g. ``3.13``, ``lint``).
3117 - - ``{env_dir}`` / ``{envdir}``
3118 - Directory of the current environment (default: ``{work_dir}/{env_name}``).
3119 - - ``{env_tmp_dir}`` / ``{envtmpdir}``
3120 - Temporary directory for the current environment (default: ``{env_dir}/tmp``).
3121 - - ``{env_log_dir}`` / ``{envlogdir}``
3122 - Log directory for the current environment (default: ``{env_dir}/log``).
3123 - - ``{env_bin_dir}`` / ``{envbindir}``
3124 - Binary directory of the virtual environment (e.g. ``{env_dir}/bin``).
3125 - - ``{env_python}`` / ``{envpython}``
3126 - Path to the Python executable in the virtual environment.
3127 - - ``{env_site_packages_dir}`` / ``{envsitepackagesdir}``
3128 - Pure-python site-packages directory (purelib) of the virtual environment.
3129 - - ``{env_site_packages_dir_plat}`` / ``{envsitepackagesdir_plat}``
3130 - Platform-specific site-packages directory (platlib) of the virtual environment.
3131 - - ``{base_python}`` / ``{basepython}``
3132 - The configured base Python interpreter.
3133 - - ``{py_dot_ver}``
3134 - Major.Minor version of the environment Python (e.g. ``3.14``).
3135 - - ``{py_impl}``
3136 - Python implementation name in lowercase (e.g. ``cpython``, ``pypy``).
3137 - - ``{py_free_threaded}``
3138 - ``True`` if the environment Python is a free-threaded build, else ``False``.
3139 - - ``{env:KEY}`` / ``{env:KEY:DEFAULT}``
3140 - Value of environment variable ``KEY``, with optional default.
3141 - - ``{posargs}`` / ``{posargs:DEFAULTS}``
3142 - Positional arguments passed after ``--``, with optional defaults.
3143 - - ``{tty:ON:OFF}``
3144 - ``ON`` value when running in an interactive terminal, ``OFF`` otherwise.
3145 - - ``{glob:PATTERN}`` / ``{glob:PATTERN:DEFAULT}``
3146 - Expand glob pattern to matching file paths (space-separated, sorted). Relative paths resolve against
3147 ``tox_root``.
3148 - - ``{/}``
3149 - OS path separator (``/`` or ``\``).
3150 - - ``{:}``
3151 - OS path list separator (``:`` or ``;``).
3152 - - ``{[section]key}`` *(INI only)*
3153 - Value of ``key`` from ``[section]`` (cross-section reference).
3154
3155 For TOML-specific replacement syntax (``replace = "ref"``, ``replace = "posargs"``, ``replace = "env"``, ``replace =
3156 "glob"``, ``replace = "if"``), see :ref:`pyproject-toml-native`.