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