Configuration¶

tox configuration can be split into two categories: core and environment specific. Core settings are options that can be set once and used for all tox environments, while environment options are applied to the given tox environment only.

System requirements¶

tox works with the following Python interpreter implementations:

CPython versions 3.11, 3.12, 3.13, 3.14, 3.15

This means tox works on the latest patch version of each of these minor versions. Previous patch versions are supported on a best effort approach.

Discovery and file types¶

With regards to the configuration format, at the moment we support the following formats:

TOML.
INI (deprecated).

Out of box tox supports five configuration locations prioritized in the following order:

        flowchart TD
    search[tox searches current directory] --> tox_ini
    tox_ini[tox.ini — INI, deprecated] -- not found --> setup_cfg[setup.cfg — INI, deprecated]
    setup_cfg -- not found --> pyproject_native[pyproject.toml — tool.tox]
    pyproject_native -- not found --> pyproject_legacy[pyproject.toml — legacy_tox_ini, deprecated]
    pyproject_legacy -- not found --> tox_toml[tox.toml — TOML]

    classDef ini fill:#dbeafe,stroke:#3b82f6,stroke-width:2px,color:#1e3a5f
    classDef toml fill:#dcfce7,stroke:#22c55e,stroke-width:2px,color:#14532d
    classDef start fill:#f3f4f6,stroke:#9ca3af,stroke-width:2px,color:#374151

    class tox_ini,setup_cfg,pyproject_legacy ini
    class pyproject_native,tox_toml toml
    class search start

tox.ini (INI, deprecated),
setup.cfg (INI, deprecated),
Native pyproject.toml under the tool.tox table (TOML),
pyproject.toml with the tool.tox table, having legacy_tox_ini key (containing INI, deprecated),
tox.toml (TOML).

Historically, the INI format was created first, and TOML was added in 2024. The INI format is deprecated – it keeps working for existing projects, but it is frozen: no new features will be added to it, and it may be removed in a future major release. Use TOML instead – it is more robust, has proper type support, and avoids ambiguities inherent in INI parsing (e.g. multi-line values, comment escaping). For existing INI configurations, see how to migrate to TOML.

Format comparison¶

Both INI and TOML support the same features with different syntax. The only INI feature without a TOML equivalent is generative section names (see below).

Conditional factors – Both INI and TOML support filtering by factor name. A factor is any dash-separated segment in the environment name (e.g. py313-django50 has factors py313 and django50). Additionally, the current platform (sys.platform value like linux, darwin, win32) is automatically available as an implicit factor. See Factors for the naming rules and for selecting environments by factor.

TOML

[env_run_base]
deps = [
    "pytest",
    { replace = "if", condition = "factor.django50", then = ["Django>=5.0,<5.1"], extend = true },
    { replace = "if", condition = "factor.django42", then = ["Django>=4.2,<4.3"], extend = true },
    { replace = "if", condition = "not factor.lint", then = ["coverage"], extend = true },
]
commands = [
    { replace = "if", condition = "factor.linux", then = [["python", "-c", "print('on linux')"]], extend = true },
    { replace = "if", condition = "factor.darwin", then = [["python", "-c", "print('on mac')"]], extend = true },
    { replace = "if", condition = "factor.win32", then = [["python", "-c", "print('on windows')"]], extend = true },
]

Use replace = "if" with factor.NAME conditions. Supports boolean operations (and, or, not) and can combine with environment variable checks (env.VAR).

INI (deprecated)

[testenv]
deps =
    pytest
    django50: Django>=5.0,<5.1
    django42: Django>=4.2,<4.3
    !lint: coverage
commands =
    linux: python -c 'print("on linux")'
    darwin: python -c 'print("on mac")'
    win32: python -c 'print("on windows")'

Supports simple factors (django50:), multiple factors (py313,py312:), and negation (!lint:). Any multi-line setting (deps, commands, set_env, etc.) can use factor conditions.

Platform factors work in any environment without requiring the platform name in the environment name.

Generative environment lists – Both INI and TOML support generating environment lists from factor combinations.

TOML

env_list = [
    "lint",
    { prefix = "3.", start = 12, stop = 14 },
    { product = [["3.12", "3.13", "3.14"], ["django42", "django50"]] },
]

Each env_list item is one of four structured shapes: a literal string, a bare range dict ({ prefix = "3.", start = 12, stop = 14 }) for a single axis, a labeled dict ({ ecosystem = ["oci", "python"] }) that also registers a {factor:label} name, or a product dict that computes the Cartesian product of multiple factor groups and joins each combination with -. A product dict also accepts an exclude key to skip specific combinations. TOML never interprets curly braces inside string items — composition is always via these dicts.

INI (deprecated)

[tox]
env_list = py3{12,13,14}-django{42,50}

Curly-brace expressions expand into the Cartesian product of all combinations. This generates 6 environments: py312-django42, py312-django50, …, py314-django50. Ranges are also supported: py3{12-14} expands to py312, py313, py314. Open-ended ranges expand to the supported CPython versions at the time of the tox release: py3{10-} expands up to the latest supported version, py3{-13} expands down to the oldest supported one.

Generative section names – INI section headers can use the same curly-brace expansion:

[testenv:py3{12,13}-{x86,x64}]
envdir =
    x86: .venv-x86
    x64: .venv-x64

TOML does not support generative section names, but you can use env_base templates (see Environment base templates) to generate multiple environments from a single definition:

[env_base.build]
factors = [["py312", "py313"], ["x86", "x64"]]
env_dir = { replace = "if", condition = "factor.x86", then = ".venv-x86", "else" = ".venv-x64" }
commands = [["python", "-c", "print('ok')"]]

This generates build-py312-x86, build-py312-x64, build-py313-x86, build-py313-x64 – each inheriting from the template and resolving factor conditions per environment.

Environment base templates¶

env_base sections define named templates that generate multiple environments from factor combinations. Each template requires a factors key – a list of factor groups whose Cartesian product determines which environments are created. The template name is joined with each factor combination using -:

[env_base.test]
factors = [["3.13", "3.14"]]
deps = ["pytest>=8"]
commands = [["pytest"]]

This generates test-3.13 and test-3.14. For multi-dimensional matrices:

[env_base.django]
factors = [["py312", "py313"], ["django42", "django50"]]
deps = [
    "pytest",
    { replace = "if", condition = "factor.django42", then = ["Django>=4.2,<4.3"], extend = true },
    { replace = "if", condition = "factor.django50", then = ["Django>=5.0,<5.1"], extend = true },
]
commands = [["pytest"]]

This generates 4 environments: django-py312-django42, django-py312-django50, django-py313-django42, django-py313-django50.

Inheritance chain: settings resolve in this order: [env.{name}] (explicit overrides) → [env_base.{template}] (template defaults) → [env_run_base] (global defaults).

Factor groups can be:

A list of strings: ["a", "b"]
A range dict: { prefix = "py3", start = 12, stop = 14 } (generates py312, py313, py314)
A labeled dict: { ecosystem = ["oci", "python"] } (same as a list, but registers the label for substitution)
A labeled range dict: { py_version = { prefix = "3.", start = 12, stop = 14 } } (a range that also registers a label)
A labeled values dict: { django_version = { values = ["django42", "django50"], default = "django50" } } (a list with a declared default)
Mixed in the same factors list for Cartesian products

The template name itself does not appear as a runnable environment – only the generated names do.

Factor label substitution¶

Added in version 4.49.0.

Factor groups can be labeled by using a single-key dict instead of a plain list. The label enables {factor:label} substitution in any string value (descriptions, commands, deps, set_env, etc.), resolving to whichever value from the labeled group is an active factor in the current environment. Every factor group also receives a positional label (0, 1, …) automatically.

Named labels – use a single-key dict to name a factor group:

[env_base.sync]
factors = [{ecosystem = ["oci", "python", "js"]}, {target = ["pw", "tt"]}]
description = "Sync {factor:ecosystem} artifacts to {factor:target}"
commands = [["sync-tool", "--ecosystem", "{factor:ecosystem}"]]

For sync-oci-pw, the description resolves to Sync oci artifacts to pw and the command receives --ecosystem oci.

A range dict takes a label when you nest it under one:

[env_base.test]
factors = [
    { py_version = { prefix = "3.", start = 12, stop = 14 } },
    { django_version = ["django42", "django50"] },
]
description = "Test on Python {factor:py_version} against {factor:django_version}"

Added in version 4.61: Labels on range dicts.

Positional labels – plain lists automatically get index-based labels:

[env_base.task]
factors = [["oci", "python"], ["pw", "tt"]]
description = "Run {factor:0} on {factor:1}"

For task-oci-pw, the description resolves to Run oci on pw. Labeled dicts also support positional access: {factor:0} and {factor:ecosystem} both resolve to oci when the labeled dict is in position 0.

In product matrices – labeled factor groups work in env_list product dicts too:

env_list = [
    { product = [["sync"], {ecosystem = ["oci", "python"]}, {target = ["pw", "tt"]}] },
]

[env_run_base]
description = "Sync {factor:ecosystem} to {factor:target}"

Defaults – {factor:label:fallback} uses fallback when the label is unknown, following the same convention as {env:VAR:default}.

A factor group can declare its own default instead, so every use site stays short:

[env_base.test]
factors = [
    { py_version = { prefix = "3.", start = 12, stop = 14 } },
    { django_version = { values = ["django42", "django50"], default = "django50" } },
]
description = "Test {factor:django_version} on Python {factor:py_version}"

A range dict takes default in the same table as prefix.

The declared default must be one of the group’s own factors. It applies when no factor of the group is active in the environment name, which happens in an [env.NAME] section outside the matrix. A {factor:label:fallback} written at the use site wins over it.

Added in version 4.61: The values and default keys.

Overriding a label for one run – set TOX_FACTOR_<label> to make {factor:<label>} resolve to that value, whatever the environment name says:

$ env TOX_FACTOR_django_version=django61 tox run -e test-3.14-django50

This installs Django61 while still running the test-3.14-django50 environment, which is useful for a one-off check against a version the matrix does not list. The variable only applies to labels the configuration declares, and it does not change which environments exist or what they are called. Setting the variable to an empty value still counts as an override, so {factor:<label>} resolves to an empty string instead of falling back to the environment’s own factor or an inline default.

Added in version 4.61: The TOX_FACTOR_<label> override.

Comparison with conditionals – {factor:label} replaces nested replace = "if" chains when the substituted value equals the factor name itself. For values that don’t match factor names (e.g., mapping pw to production-west-cluster), use replace = "if" with factor.NAME conditions.

Reserved names – the following cannot be used as label names: env, posargs, tty, glob, factor.

`tox.ini`¶

This configuration file uses:

tox section to host core configuration,
testenv:{env_name} section to host environment configuration,
testenv section as base configuration for run environments (fallback location for missing values for a test/run environment),
pkgenv section as base configuration for package environments (fallback location for missing values for a package environment).

For example:

[tox]
requires =
    tox >= 4.20
env_list =
    3.14t
    3.14
    3.13
    3.12
    type

[testenv]
deps = pytest
commands = pytest tests

[testenv:type]
deps = mypy
commands = mypy src

`setup.cfg`¶

This configuration file uses:

tox:tox section to host core configuration,
testenv:{env_name} section to host environment configuration,
testenv section as base configuration for run environments (fallback location for missing values for a test/run environment),
pkgenv section as base configuration for package environments (fallback location for missing values for a package environment).

[tox:tox]
requires =
    tox >= 4.0
env_list =
    3.14t
    3.14
    3.13
    3.12
    type

[testenv]
deps = pytest
commands = pytest tests

[testenv:type]
deps = mypy
commands = mypy src

`pyproject.toml` - INI¶

This configuration file is equivalent to tox.ini format, with the difference that the text is stored instead inside the pyproject.toml file under the tool.tox table and legacy_tox_ini key:

[tool.tox]
legacy_tox_ini = """
    [tox]
    requires =
        tox >= 4.0
    env_list =
        3.14
        3.13
        3.12
        type

    [testenv]
    deps = pytest
    commands = pytest tests

    [testenv:type]
    deps = mypy
    commands = mypy src
"""

`pyproject.toml` - native¶

We support native TOML configuration via the pyproject.toml files tool.tox table. This configuration file uses:

tool.tox table to host core configuration,
tool.tox.env.{env_name} table to host environment configuration,
tool.tox.env_run_base table as base configuration for run environments (fallback location for missing values for a test/run environment),
tool.tox.env_pkg_base table as base configuration for package environments (fallback location for missing values for a package environment).

[tool.tox]
requires = ["tox>=4.19"]
env_list = ["3.14t", "3.14", "3.13", "3.12", "type"]

[tool.tox.env_run_base]
description = "Run test under {base_python}"
commands = [["pytest"]]

[tool.tox.env.type]
description = "run type check on code base"
deps = ["mypy==1.18.2", "types-cachetools>=5.5.0.20240820", "types-chardet>=5.0.4.6"]
commands = [["mypy", "src{/}tox"], ["mypy", "tests"]]

`tox.toml`¶

This configuration file is equivalent to pyproject.toml - native with the difference that it lives in a separate dedicated files and accordingly the tool.tox sub-table is no longer required.

For example:

requires = ["tox>=4.19"]
env_list = ["3.14t", "3.14", "3.13", "3.12", "type"]

[env_run_base]
description = "Run test under {base_python}"
commands = [["pytest"]]

[env.type]
description = "run type check on code base"
deps = ["mypy==1.18.2", "types-cachetools>=5.5.0.20240820", "types-chardet>=5.0.4.6"]
commands = [["mypy", "src{/}tox"], ["mypy", "tests"]]

Core¶

The following options are set in the [tox] section of tox.ini, the [tox:tox] section of setup.cfg, or the top level of tox.toml. Placing these options in an environment section (e.g. [testenv]) has no effect. Run tox config or tox run -v to check for misplaced keys.

⚙️ requires with default value of tox 📢 added in 3.2.0

Specify a list of PEP 508 compliant dependencies that must be satisfied in the Python environment hosting tox when running the tox command. If any of these dependencies are not satisfied will automatically create a provisioned tox environment that does not have this issue, and run the tox command within that environment. See provision_tox_env for more details. tox always appends itself to this list, as tox>=<min_version> when min_version is set.

A requirement containing a line break or ending in a backslash is refused before provisioning installs it.

For a direct URL requirement, tox checks the installed distribution’s PEP 610 direct_url.json against the requested URL, subdirectory, and supported archive hash. pip discards fragment fields such as egg; these do not affect origin matching. Missing or different origin metadata triggers provisioning. Installers must omit sensitive URL credentials from that record. If credentials are omitted, tox cannot verify a credentialed direct URL without an archive hash and reports an error. Pin a sha256 archive hash to verify it. In INI configuration, escape the fragment marker as \#; TOML strings keep # unchanged.
TOML
[tool.tox]
requires = [
  "tox>=4",
  "virtualenv>20.2",
]
INI (deprecated)
[tox]
requires =
    tox>=4
    virtualenv>20.2

⚙️ min_version minversion with default value of unset 📢 added in 2.4 ⚠️ deprecated in 4.28.0

DEPRECATED Prefer requiring a minimum tox version via requires.

A string to define the minimal tox version required to run. If the host’s tox version is less than this, it will automatically create a provisioned tox environment that satisfies this requirement. See provision_tox_env for more details.

⚙️ provision_tox_env with default value of .tox 📢 added in 3.8.0

Name of the tox environment used to provision a valid tox run environment.

Note

The provisioning environment does not inherit settings from env_run_base (TOML) or [testenv] (INI). It must be explicitly configured if you need to customize it (e.g. env.".tox" in TOML or [testenv:.tox] in INI).

Changed in version 3.23.0: When tox is invoked with the --no-provision flag, the provision won’t be attempted, tox will fail instead.

⚙️ env_list envlist with default value of <empty list> 📢 added in 1.0

A list of environments to run by default (when the user does not specify anything during the invocation).

In INI configuration, a substitution within an environment name cannot add a comma, line break or brace group. Put a substitution on its own entry when it is meant to supply several environments.

Changed in version 3.4.0: Which tox environments are run during the tox invocation can be further filtered via the operating system environment variable TOX_SKIP_ENV regular expression (e.g. py27.* means don’t evaluate environments that start with the key py27). Skipped environments will be logged at level two verbosity level.

⚙️ skip_missing_interpreters with default value of False 📢 added in 1.7.2

Setting this to true will force tox to return success even if some of the specified environments were missing. This is useful for some CI systems or when running on a developer box, where you might only have a subset of all your supported interpreters installed but don’t want to mark the build as failed because of it. The --skip-missing-interpreters command line switch overrides this setting, unless you pass it config.

⚙️ tox_root toxinidir 📢 added in 1.6.1

The root directory for the tox project. By default, this is the directory containing the configuration file; tox resolves a relative override against that directory.

For relative values of work_dir, temp_dir, package_root, env_dir, env_tmp_dir, env_log_dir, meta_dir, pkg_dir and package_glob, tox uses tox_root as the base, including when tox starts elsewhere with -c. Absolute values keep their configured location.

■ config_file_path

A constant holding the path of the configuration file tox loaded.

■ tox_root_name

A constant holding the name of the tox_root directory. Combine it with {home} to give each project its own location outside the project tree, as work_dir shows.

■ home

A constant holding the user’s home directory.

⚙️ work_dir toxworkdir with default value of {tox_root}/.tox 📢 added in 1.0 🔄 changed in 4.60

Directory for tox to generate its environments into, will be created if it does not exist.

Use the {home} and {tox_root_name} substitutions to keep tox environments outside of the project tree, in a location unique per project, similar to virtualenvwrapper:
work_dir = "{home}/.local/state/tox/{tox_root_name}"
tox resolves a relative configured value against tox_root. The --workdir CLI flag and the user-level configuration file take the value as a literal path, without substitution. See Keep environments outside the project tree for a walk-through and Work directory placement for the trade-offs.

⚙️ temp_dir with default value of {work_dir}/.tmp 📢 added in 3.5

Directory for tox temporary files. Each package build creates a separate copy here so parallel runs do not share the same staged package.

If this directory is a symlink inside work_dir, tox replaces the link with a directory. A configured path outside work_dir may remain a symlink. On POSIX, package staging rejects a path that an account unable to change the project directory can rename. A work directory left writable by such accounts is made private and emptied once at the start of a run, so tox recreates its environments. If package staging needs new work, temporary or staging directories, tox creates them with owner-only access. Existing directories that only the project’s writers can change keep their permissions.

⚙️ venv_redirect with default value of unset 📢 added in 4.64.0

Warning

This option is provisional because PEP 832 is still a draft, and tox follows the PEP as it changes. A minor or patch release may change this option, venv_redirect_env and the file tox writes in backward incompatible ways.

Point a PEP 832 .venv redirect file next to the configuration file at a tox environment, so that editors such as VS Code or PyCharm offer it as the project interpreter. The file holds a single line: the environment directory, relative to the file with forward slashes when it lives under the project, absolute otherwise. tox writes it at the end of a run for the environment named by venv_redirect_env or, when that is unset, one named dev, else the first that installs the project in development mode. Without such an environment tox writes nothing, and it waits until the picked environment exists instead of pointing at another one. tox removes the file while it recreates the environment it points at. tox devenv points the file at the environment it creates, replacing any redirect file, and later runs leave that redirect in place. tox tells virtualenv to write no redirect file of its own.

tox leaves a .venv directory or symlink alone, and a redirect file pointing outside the work_dir and the tox environments, since then the user or another tool chose the environment.

On Windows, tox warns instead of writing a redirect when any directory in the project path is a reparse point, such as a symlink or junction.

Left unset, tox writes the redirect file unless a tox environment’s env_dir is the .venv path, since that environment is the project’s .venv. With true, tox writes it and fails the run before any environment starts when such an environment exists; with false, tox writes nothing. When a file sits where an environment should live, tox deletes it if it is a redirect file tox wrote, and otherwise fails that environment with an error naming the file.

⚙️ venv_redirect_env 📢 added in 4.64.0

This option is provisional, like venv_redirect.

The name of the tox environment the .venv redirect file points at, overriding the pick described under venv_redirect. tox writes nothing while that environment does not exist, and warns when no environment has the name.

⚙️ no_package skipsdist with default value of false 📢 added in 1.6

Flag indicating to perform the packaging operation or not. Set it to true when using tox for an application, instead of a library.

⚙️ package_env isolated_build_env with default value of .pkg 📢 added in 3.3.0

Default name of the virtual environment used to create a source distribution from the source tree.

⚙️ package_root setupdir with default value of {tox_root} 📢 added in 1.0

Directory containing build metadata, such as pyproject.toml or setup.py. A packaging environment can set its own value for the build source, static package dependencies, and editable-legacy installs. pylock files and dependency_groups use the core package_root.

⚙️ labels with default value of <empty dictionary> 📢 added in 4.0

A mapping of label names to environments it applies too. For example:

TOML

[tool.tox]
labels = { test = ["3.14t", "3.14", "3.13", "3.12"], static = ["ruff", "mypy"] }

INI (deprecated)

[tox]
labels =
     test = 3.14t, 3.14, 3.13, 3.12
     static = ruff, mypy

■ on_platform 📢 added in 4.17

A constant holding the platform of the tox runtime environment.

■ host_python

A constant holding the path of the Python interpreter running tox itself, rather than that of any tox environment.

Python language core options¶

⚙️ ignore_base_python_conflict ignore_basepython_conflict with default value of False 📢 added in 3.1

Added in version 3.1.0.

tox allows setting the Python version for an environment via the base_python setting. If that’s not set tox can set a default value from the environment name (e.g. 3.10 or py310 implies Python 3.10). Matching up the Python version with the environment name has became expected at this point, leading to surprises when some configs don’t do so. To help with sanity of users, an error will be raised whenever the environment name version does not match up with this expectation.

Furthermore, we allow hard enforcing this rule by setting this flag to true. In such cases we ignore the base_python and instead always use the base Python implied from the Python name. This allows you to configure base_python in the base section without affecting environments that have implied base Python versions.

This flag handles two types of conflicts:

Explicit setting vs. environment name: When base_python is explicitly set but conflicts with the version extracted from the environment name. Setting this to true uses the version from the environment name.

Multiple version factors in environment name (since 4.47.3): When the environment name itself contains multiple factors that look like Python versions (e.g., unit-py3.10-2.16 where both py3.10 and 2.16 match Python version patterns). Setting this to true falls back to default_base_python instead of raising an error. To avoid this ambiguity, prefix non-Python version factors (e.g. use ac2.16 instead of 2.16).

tox environment¶

These are configuration for the tox environments (either packaging or run type). Set these in [testenv] (INI), env_run_base (TOML), or per-environment sections. Placing these options in the core [tox] section has no effect. Run tox config or tox run -v to check for misplaced keys.

Base options¶

■ envname env_name 📢 added in 4.0

The name of the tox environment.

⚙️ env_dir envdir with default value of {work_dir}/{env_name} 📢 added in 1.5

Directory assigned to the tox environment. tox resolves a relative value against tox_root.

⚙️ env_tmp_dir envtmpdir with default value of {work_dir}/{env_name}/tmp 📢 added in 0.5

A folder that is always reset at the start of the run.

An empty path, including one produced by an unset {env:...} substitution, is a configuration error.

⚙️ env_log_dir envlogdir with default value of {work_dir}/{env_name}/log 📢 added in 0.5

A folder containing log files about tox runs. It’s always reset at the start of the run. Currently contains every process invocation in the format of <index>-<run name>.log, and details the execution request (command, environment variables, current working directory, etc.) and its outcome (exit code and standard output/error content).

⚙️ platform 📢 added in 2.0

Run on platforms that match this regular expression (empty means any platform). If a non-empty expression is defined and does not match against the sys.platform string the entire test environment will be skipped and none of the commands will be executed. An invalid regular expression fails the environment instead of skipping it. Running tox -e <platform_name> will run commands for a particular platform and skip the rest.

⚙️ pass_env passenv with default value of <empty list> 📢 added in 2.0

Environment variables to pass on to the tox environment. The values are evaluated as UNIX shell-style wildcards, see fnmatch If a specified environment variable doesn’t exist in the tox invocation environment it is ignored. The list of environment variable names is not case sensitive, for example: passing A or a will pass through both A and a.

Some variables are always passed through to ensure the basic functionality of standard library functions or tooling like pip. This is also not case sensitive on all platforms except Windows.

Environment Variables per Operating System¶

Environment Variable

Linux

MacOS

Windows

https_proxy

✅

✅

✅

http_proxy

✅

✅

✅

no_proxy

✅

✅

✅

LANG

✅

✅

✅

LANGUAGE

✅

✅

✅

CURL_CA_BUNDLE

✅

✅

✅

SSL_CERT_FILE

✅

✅

✅

CC

✅

✅

✅

CFLAGS

✅

✅

✅

CCSHARED

✅

✅

✅

CXX

✅

✅

✅

CPPFLAGS

✅

✅

✅

LD_LIBRARY_PATH

✅

✅

✅

LDFLAGS

✅

✅

✅

HOME

✅

✅

✅

FORCE_COLOR

✅

✅

✅

NO_COLOR

✅

✅

✅

TMPDIR

✅

✅

❌

TEMP

❌

❌

✅

TMP

❌

❌

✅

USERPROFILE

❌

❌

✅

PATHEXT

❌

❌

✅

MSYSTEM

❌

❌

✅

WINDIR

❌

❌

✅

APPDATA

❌

❌

✅

LOCALAPPDATA

❌

❌

✅

PROGRAMDATA

❌

❌

✅

PROGRAMFILES(x86)

❌

❌

✅

SYSTEMDRIVE

❌

❌

✅

SYSTEMROOT

❌

❌

✅

COMSPEC

❌

❌

✅

PROCESSOR_ARCHITECTURE

❌

❌

✅

NUMBER_OF_PROCESSORS

❌

❌

✅

PIP_*

✅

✅

✅

VIRTUALENV_*

✅

✅

✅

NETRC

✅

✅

✅

NIX_LD*

✅

✅

❌

NIX_LD_LIBRARY_PATH

✅

✅

❌

PYTHON_GIL

✅

✅

✅

SSH_AGENT_PID

✅

✅

❌

SSH_AUTH_SOCK

✅

✅

❌

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.

More environment variable-related information can be found in Environment variable substitutions.

Environment Variables per Operating System¶
Environment Variable	Linux	MacOS	Windows
https_proxy	✅	✅	✅
http_proxy	✅	✅	✅
no_proxy	✅	✅	✅
LANG	✅	✅	✅
LANGUAGE	✅	✅	✅
CURL_CA_BUNDLE	✅	✅	✅
SSL_CERT_FILE	✅	✅	✅
CC	✅	✅	✅
CFLAGS	✅	✅	✅
CCSHARED	✅	✅	✅
CXX	✅	✅	✅
CPPFLAGS	✅	✅	✅
LD_LIBRARY_PATH	✅	✅	✅
LDFLAGS	✅	✅	✅
HOME	✅	✅	✅
FORCE_COLOR	✅	✅	✅
NO_COLOR	✅	✅	✅
TMPDIR	✅	✅	❌
TEMP	❌	❌	✅
TMP	❌	❌	✅
USERPROFILE	❌	❌	✅
PATHEXT	❌	❌	✅
MSYSTEM	❌	❌	✅
WINDIR	❌	❌	✅
APPDATA	❌	❌	✅
LOCALAPPDATA	❌	❌	✅
PROGRAMDATA	❌	❌	✅
PROGRAMFILES(x86)	❌	❌	✅
SYSTEMDRIVE	❌	❌	✅
SYSTEMROOT	❌	❌	✅
COMSPEC	❌	❌	✅
PROCESSOR_ARCHITECTURE	❌	❌	✅
NUMBER_OF_PROCESSORS	❌	❌	✅
PIP_*	✅	✅	✅
VIRTUALENV_*	✅	✅	✅
NETRC	✅	✅	✅
NIX_LD*	✅	✅	❌
NIX_LD_LIBRARY_PATH	✅	✅	❌
PYTHON_GIL	✅	✅	✅
SSH_AGENT_PID	✅	✅	❌
SSH_AUTH_SOCK	✅	✅	❌

⚙️ disallow_pass_env with default value of <empty list> 📢 added in 4.36

Environment variable patterns to exclude after pass_env glob expansion. Uses the same fnmatch wildcard syntax as pass_env. Applied after pass_env patterns are resolved against the host environment and before set_env values are applied:
TOML
[env_run_base]
pass_env = ["FOO_*"]
disallow_pass_env = ["FOO_SECRET"]
INI (deprecated)
[testenv]
pass_env = FOO_*
disallow_pass_env = FOO_SECRET
In this example, all environment variables matching FOO_* are passed through except FOO_SECRET.

⚙️ set_env setenv 📢 added in 1.0

A dictionary of environment variables to set when running commands in the tox environment.

In addition, there is an option to include an existing environment file. See the different syntax for TOML and INI below.
TOML
[tool.tox.env_run_base]
set_env = { file = "conf{/}local.env", TEST_TIMEOUT = "30" }
INI (deprecated)
[testenv]
set_env = file|conf{/}local.env
     TEST_TIMEOUT = 30
The env file path may include previously defined tox variables:
TOML
[tool.tox.env_run_base]
set_env = { file = "{env:variable}" }
INI (deprecated)
[testenv]
set_env = file|{env:variable}
Note

Environment files are processed using the following rules:

lines end at LF, CRLF or CR; an embedded Unicode separator does not start another entry,

blank lines are ignored,

lines starting with the # character are ignored,

each line is in KEY=VALUE format; both the key and the value are stripped,

NUL characters in keys and values are rejected,

a leading export followed by a space or tab is ignored, so export KEY=value sets KEY,

there is no special handling of quotation marks, they are part of the key or value,

PEP-508 markers are not supported in environment files, so a ; is a plain value character.

A line without = fails with the file path and line number. tox omits the line’s text from the error.
Conditional environment variables

Added in version 4.33.

Environment variables can be set conditionally based on PEP-508 environment markers. If the marker evaluates to false, the variable will not be set.

Note

Markers are evaluated against the Python interpreter running tox (the host Python), not the target environment’s Python interpreter. This means markers like python_version reflect tox’s Python version, not the target’s. For platform-specific conditions (e.g., sys_platform, os_name), this is typically the desired behavior since the target environment runs on the same platform.
TOML
[tool.tox.env_run_base]
set_env.LINUX_VAR = { value = "1", marker = "sys_platform == 'linux'" }
set_env.WIN_VAR = { value = "1", marker = "sys_platform == 'win32'" }

# Can also be combined with replace directives
set_env.CONDITIONAL = { replace = "env", name = "MY_VAR", default = "fallback", marker = "sys_platform == 'linux'" }
INI (deprecated)
[testenv]
set_env =
    LINUX_VAR = 1; sys_platform == 'linux'
    DARWIN_VAR = 1; sys_platform == 'darwin'
    WIN_ONLY = 1; sys_platform == 'win32'
The KEY = VALUE; marker syntax applies to INI set_env lines and to --override values for set_env in both formats. TOML tables carry the marker in its own marker field, so their values take ;, quotes and backslashes literally. In the line syntax:

write a literal semicolon as \; so it is not parsed as a marker separator; in an INI file, C:\tools\\;C:\bin sets C:\tools\;C:\bin,

a ; inside balanced quotes stays in the value, and so do the quotes,

\" does not close a quote, while \\" does, so "C:\tools;C:\bin\\" is one value.

Available markers include sys_platform, os_name, platform_machine, platform_system, python_version, implementation_name, and others as defined in PEP-508.

For conditional settings that should differ per target Python environment (e.g., based on Python version), use tox’s conditional settings mechanism with environment factors instead.

How tox resolves set_env

set_env differs from every other key: tox reads its structure when it loads the environment, and substitutes each value only when it reads that value. These rules follow from that and hold for both TOML and INI:

{env:KEY} in a value sees every key the environment’s set_env ends up with, whether the key comes from the same table, an included section, or an environment file. It falls back to the host variable only when no set_env key matches, see Environment variable substitutions.

A value that refers to its own key, PATH = {env:PATH}{:}/extra, reads the host variable.

Including another section’s set_env behaves as if you wrote its lines in place. In INI that is {[section]set_env}; in TOML it is { replace = "ref", of = [...] }. The included values resolve in the including environment, so {env_name} and {posargs} refer to that environment. Naming an environment whose section has no set_env of its own includes the lines that environment inherits.

When two lines set the same key, a key written directly in a set_env wins over the same key from an included section, and a later included section wins over an earlier one. The rule applies again inside every included section. In the TOML list form, the later entry wins.

A { replace = "env" } table resolves like the {env:...} string it stands for, so rule 1 applies to it too.

A section that includes itself, directly or through other sections, a TOML ref that refers to itself, and values that refer to each other (A = {env:B}, B = {env:A}) fail the environment with an error that names the chain.

A substitution in an INI key, such as LABEL_{env_name} = {env:LABEL}, resolves while tox reads the structure. Its value resolves when read, as it does with a literal key. A key that expands to = or a line separator fails with an error.
TOML
[tool.tox.env.base]
set_env = { BASE = "/opt/app", DATA = "{env:BASE}/data", LOGS = { replace = "env", name = "BASE" } }

[tool.tox.env.integration]
set_env = { replace = "ref", of = ["tool", "tox", "env", "base", "set_env"] }
INI (deprecated)
[base]
set_env =
    BASE = /opt/app
    DATA = {env:BASE}/data

[testenv:integration]
set_env =
    {[base]set_env}
    EXTRA = 1
Both forms set DATA to /opt/app/data in integration, whatever BASE holds on the host. See Share environment variables between environments for recipes and Why set_env resolves values late for the reasoning.

Note

Earlier releases resolved values pulled in with {[section]set_env} and { replace = "env" } tables before the other keys existed, so they read the host variable. A nested section could override the section that included it, and cycles failed with a traceback or “could not find python interpreter”.

Note

Changing installer-relevant environment variables via set_env (e.g. PIP_INDEX_URL, PIP_EXTRA_INDEX_URL) invalidates the install cache and triggers a reinstall on the next run. Only variables known to affect package resolution are tracked; cosmetic or performance variables such as PIP_TIMEOUT or PIP_VERBOSE do not affect the cache. Plugin-based installers (e.g. tox-uv) extend this list with their own resolution-affecting variables.

More environment variable-related information can be found in Environment variable substitutions.

Injected environment variables¶

tox automatically injects several environment variables into the test environment when running commands. These are always set regardless of the pass_env or set_env configuration and cannot be overridden by the user.

Variable	Description
`TOX_ENV_NAME`	The name of the current tox environment (e.g. `3.12`, `lint`).
`TOX_WORK_DIR`	The tox working directory (by default `.tox` under the project root).
`TOX_ENV_DIR`	The directory of the current tox environment (e.g. `.tox/3.12`).
`PYTHONIOENCODING`	Always set to `utf-8` to ensure consistent encoding for standard I/O.
`PIP_USER`	Always set to `0` to prevent pip from attempting `--user` installs inside virtualenvs, which would fail because user site-packages aren’t visible. Only set when using `virtualenv`-based environments.
`TOX_PACKAGE`	The path(s) to the built package artifact(s), joined by `os.pathsep` if there are multiple. Only set in run environments where a package has been built. See Reference the built package path in commands for usage examples.
`VIRTUAL_ENV`	The path to the virtual environment directory. Only set when using `virtualenv`-based environments (the default).
`__TOX_ENVIRONMENT_VARIABLE_ORIGINAL_CI`	The value of the `CI` environment variable from the host. Only set when the `CI` variable is present in the host environment.

Note

In tox 3, TOX_PARALLEL_ENV was injected during parallel runs. This variable is no longer injected in tox 4.

⚙️ parallel_show_output with default value of False 📢 added in 3.7

If set to True the content of the output will always be shown when running in parallel mode.

⚙️ recreate with default value of False 📢 added in 0.9

Always recreate virtual environment if this option is true, otherwise leave it up to tox.

⚙️ allowlist_externals with default value of <empty list> 📢 added in 1.5

Each line specifies a command name (in glob-style pattern format) which can be used in the commands section even if it’s located outside of the tox environment. For example: if you use the unix rm command for running tests you can list allowlist_externals=rm or allowlist_externals=/usr/bin/rm. If you want to allow all external commands you can use allowlist_externals=* which will match all commands (not recommended).

⚙️ labels with default value of <empty list> 📢 added in 4.0

A list of labels to apply for this environment. For example:

TOML

[tool.tox.env_run_base]
labels = ["test", "core"]
[tool.tox.env.flake8]
labels = ["mypy"]

INI (deprecated)

[testenv]
labels = test, core
[testenv:flake8]
labels = mypy

Execute¶

⚙️ suicide_timeout with default value of 0.0 📢 added in 3.15.2

When an interrupt is sent via Ctrl+C or the tox process is killed with a SIGTERM, a SIGINT is sent to all foreground processes. The suicide_timeout gives the running process time to cleanup and exit before receiving (in some cases, a duplicate) SIGINT from tox.

⚙️ interrupt_timeout with default value of 0.3 📢 added in 3.15

When tox is interrupted, it propagates the signal to the child process after suicide_timeout seconds. If the process still hasn’t exited after interrupt_timeout seconds, its sends a SIGTERM.

⚙️ terminate_timeout with default value of 0.2 📢 added in 3.15

When tox is interrupted, after waiting interrupt_timeout seconds, it propagates the signal to the child process, waits interrupt_timeout seconds, sends it a SIGTERM, waits terminate_timeout seconds, and sends it a SIGKILL if it hasn’t exited.

Packaging environment configuration¶

Packaging environments (such as .pkg and .pkg-cpython314) are tox environments used to build your project’s package. Unlike run environments, packaging environments do not inherit from the env_run_base table (TOML) or [testenv] section (INI). This is intentional — test environment settings often conflict with packaging settings.

Instead, packaging environments inherit from the env_pkg_base table (TOML) or [pkgenv] section (INI). This allows you to define common packaging settings in one central place, while still overriding them for specific packaging environments when needed.

TOML

[env_pkg_base]
pass_env = ["PKG_CONFIG", "PKG_CONFIG_PATH", "PKG_CONFIG_SYSROOT_DIR"]

[env.".pkg-cpython311"]
pass_env = ["PKG_CONFIG", "PKG_CONFIG_PATH", "PKG_CONFIG_SYSROOT_DIR", "IS_311"]

INI (deprecated)

[pkgenv]
pass_env =
    PKG_CONFIG
    PKG_CONFIG_PATH
    PKG_CONFIG_SYSROOT_DIR

[testenv:.pkg-cpython311]
pass_env =
    {[pkgenv]pass_env}
    IS_311 = yes

Note

Specific packaging environments are defined under [testenv:.pkg] and not [pkgenv:.pkg]. The [pkgenv] section (or env_pkg_base in TOML) serves only as the base/fallback for settings shared across all packaging environments.

Changed in version 4.2: Packaging environments now inherit from the [pkgenv] / env_pkg_base section.

Python options¶

⚙️ base_python basepython with default value of <{env_name} python factor> or <python version of tox> 📢 added in 0.5

Name or path to a Python interpreter which will be used for creating the virtual environment, first one found wins. This determines in practice the Python for what we’ll create a virtual isolated environment. Use this to specify the Python version for a tox environment. If not specified, the virtual environments factors (e.g. name part) will be used to automatically set one. For example, py310 means python3.10, py3 means python3 and py means python. If the name does not match this pattern, default_base_python is consulted, and if that is also not set, the same Python version tox is installed into will be used. An explicitly configured empty value fails during configuration. Empty entries in a list are ignored when another interpreter remains. A base interpreter ending with t means that only free threaded Python implementations are accepted. When the environment name specifies an implementation (such as pypy39), validation compares it with the interpreter’s reported implementation without regard to case. Version and build constraints still apply.

The preferred naming convention is N.M (e.g. 3.14, 3.13) rather than pyNMM (e.g. py314, py313). The dotted form is clearer, avoids ambiguity for Python versions >= 3.10, and reads more naturally in environment lists and CI output.

Warning

Any factor matching the pattern 2.N or 3.N (where N is one or more digits) is treated as a Python version specifier. This means non-Python versions like 2.16 in an environment name such as unit-py3.10-2.16 will conflict with the py3.10 factor. To avoid this, prefix non-Python version numbers (e.g. ac2.16), or set ignore_base_python_conflict to true.

Added in version 4.46: You can append a CPU architecture (ISA) suffix to constrain the interpreter to a specific machine type. The architecture is derived from sysconfig.get_platform() and normalized by virtualenv (e.g. amd64 becomes x86_64, aarch64 becomes arm64). Examples:

cpython3.12-64-arm64 — CPython 3.12, 64-bit, ARM

cpython3.13-64-x86_64 — CPython 3.13, 64-bit, x86-64

If the discovered interpreter’s architecture does not match the requested one, tox raises a failure, just as it does for version mismatches. This is useful on machines with multi-architecture support (e.g. Apple Silicon running both arm64 and x86_64 via Rosetta, or Linux with aarch64 and x86_64 via qemu-user).

Changed in version 3.1: After resolving this value if the interpreter reports back a different version number than implied from the name a warning will be printed by default. However, if ignore_basepython_conflict is set, the value is ignored and we force the base_python implied from the factor name.

Note

Leaving this unset will cause an error if the package under test has a different Python requires than tox itself and tox is installed into a Python that’s not supported by the package. For example, if your package requires Python 3.10 or later, and you install tox in Python 3.9, when you run a tox environment that has left this unspecified tox will use Python 3.9 to build and install your package which will fail given it requires 3.10.

⚙️ default_base_python with default value of <python version of tox> 📢 added in 4.42

Fallback Python interpreter used when the environment name contains no Python factor and no explicit base_python is set. Accepts a list of specifications – the first one found wins. This provides a way to pin a default Python version for reproducibility across different machines without conflicting with pyXY factor-named environments.

The resolution order for an environment’s Python interpreter is:

Python factor extracted from the environment name (e.g. 3.13, py313)

Explicit base_python setting on the environment

base_python_file — read from a version file

default_base_python (this setting)

The Python running tox (sys.executable)
TOML
[env_run_base]
default_base_python = ["3.14", "3.13"]
INI (deprecated)
[testenv]
default_base_python = 3.14, 3.13

⚙️ base_python_file with default value of <empty string> 📢 added in 4.51

A path to a file containing the Python version to use for the environment (e.g. .python-version). The first non-blank, non-comment line in the file is used as the Python version specifier. This is useful for tool environments (such as mypy or coverage) where you want a single source of truth for the default Python version without hardcoding it in the tox configuration.

This option is only consulted when base_python is not explicitly set and the environment name does not contain a Python factor (e.g. py314). See default_base_python for the full resolution order.
TOML
[env.mypy]
base_python_file = [".python-version", ".python-version-default"]
INI (deprecated)
[testenv:mypy]
base_python_file = .python-version, .python-version-default
That line must be a Python version specifier, such as 3.13, 3.13.1, pypy3.10 or 3.14t. Interpreter paths, program names and the system keyword are rejected. A version line may contain at most 1024 characters. Comment and blank lines can be longer.

■ env_site_packages_dir envsitepackagesdir 📢 added in 1.4.3

The Python environments site package - where pure-python packages are installed (the purelib folder path).

■ env_site_packages_dir_plat envsitepackagesdir_plat 📢 added in 4.42

The Python environments platform-specific site package (the platlib folder path). On most platforms this is the same as env_site_packages_dir, but on some Linux distributions (Fedora, RHEL) platlib resolves to lib64 instead of lib.

■ env_bin_dir envbindir 📢 added in 0.5

The binary folder where console/gui scripts are generated during installation.

■ env_python envpython 📢 added in 0.5

The Python executable from within the tox environment.

■ py_dot_ver 📢 added in 4.0.10

Major.Minor version of the Python interpreter in the tox environment (e.g., 3.14).

■ py_impl 📢 added in 4.0.10

Name of the Python implementation in the tox environment in lowercase (e.g., cpython, pypy).

■ py_free_threaded 📢 added in 4.26

True if the Python interpreter in the tox environment is a free-threaded CPython build, else False.

■ py_debug 📢 added in 4.57

True if the Python interpreter in the tox environment is a debug (Py_DEBUG) build, else False.

Python run¶

⚙️ dependency_groups with default value of <empty list> 📢 added in 4.22

A list of names of dependency groups (as defined by PEP 735) to install into this Python environment. The installation will happen before installing the package or any of its dependencies.

A self-reference such as demo_pkg[extra_1] expands the project’s optional-dependencies. Project and extra names ignore case and treat each run of -, _, or . as -. This example resolves to pytest>=8:
[project]
name = "demo-pkg"

[project.optional-dependencies]
extra_1 = ["pytest>=8"]

[dependency-groups]
test = ["Demo.Pkg[extra-1]"]
A marker on the self-reference applies to every requirement it expands to, so with "demo-pkg[extra-1]; sys_platform == 'win32'" the group resolves to pytest>=8; sys_platform == "win32".

For example:
TOML
[dependency-groups]
test = [
   "pytest>=8",
]

[tool.tox.env_run_base]
dependency_groups = [
  "test",
]
INI (deprecated)
[testenv]
dependency_groups =
    test
[dependency-groups]
test = [
   "pytest>=8",
]

⚙️ pylock with default value of <empty string> 📢 added in 4.44

Path to a PEP 751 pylock.toml lock file to install locked dependencies from. Mutually exclusive with deps. Each package in the lock file is filtered by evaluating its environment markers against the target Python interpreter and the configured extras and dependency_groups, then converted to a pip requirement and installed with --no-deps. The path is resolved relative to the package_root (or tox_root if no package root is configured). Change detection is automatic: adding, removing, or changing packages triggers environment recreation as needed. See Lock file installation (PEP 751) for details.

tox rejects whitespace or control characters in archive and VCS fields written to pip’s requirements file, as well as hash tokens. The check includes values pip expands from ${VAR} references in those fields.

For example:
TOML
[tool.tox.env_run_base]
pylock = "pylock.toml"
INI (deprecated)
[testenv]
pylock = pylock.toml

⚙️ deps with default value of <empty list> 📢 added in 0.5

Python dependencies. Installed into the environment prior to project after environment creation, but before package installation. All installer commands are executed using the tox_root as the current working directory. Each value must be one of:

a Python dependency as specified by PEP 440,

a requirement file when the value starts with -r (followed by a file path or URL),

a constraint file when the value starts with -c (followed by a file path or URL).

A referenced requirements file may use pip’s per-requirement --config-settings (-C) option. Put the option in that file, on the requirement line; it is not supported on a deps entry itself.

tox rejects requirement and constraint files larger than 10 MiB. For HTTP(S) files, it checks a 120-second deadline between response body reads. A server that sends HTTP framing bytes slowly can delay the check.

A substitution inside a dependency or option entry cannot add a requirements-file line. tox refuses a line break in that value, or a backslash at the end of a substituted line, before starting pip. A partial substitution also cannot add, remove, or split parsed pip option tokens. This includes ${VAR} expansion. tox still accepts options written on the same line in the configuration. A substitution alone in its entry, such as {[testenv]deps}, can still supply multiple requirements. tox also refuses a globbed requirement path containing a line break or ending in a backslash.

tox expands ${NAME} written in dependency entries and referenced requirement or constraint files from the installer environment. Add a host variable to pass_env (unless disallow_pass_env excludes it), or define it with set_env, to make it available. Otherwise the reference stays unexpanded. The same rule applies to nested -r and -c files.

If you are only defining PEP 508 requirements (aka no pip requirement files), you should use dependency_groups instead.
For example:
TOML
[tool.tox.env_run_base]
deps = [
  "pytest>=8",
  "-r requirements.txt",
  "-c constraints.txt",
]
INI (deprecated)
[testenv]
deps =
    pytest>=7,<8
    -r requirements.txt
    -c constraints.txt
Note

constraints is the preferred way to specify constraints files since they will apply to package dependencies also.

⚙️ constraints with default value of <empty list> 📢 added in 4.28.0

Constraints files to use during package and dependency installation. Provided constraints files will be used when installing package dependencies and any additional dependencies specified in deps, but will not be used when installing the package itself. Each value must be a file path or URL. A substitution within one value cannot add a line break, end a line with a backslash, or add a parsed pip option. tox still accepts options written on the same line in the configuration. Variable references inside these files follow the deps expansion rules. The file size and remote body deadline described under deps also apply.

⚙️ use_develop usedevelop with default value of false 📢 added in 1.6

Install the current package in development mode using PEP 660. This means that the package will be installed in-place and editable.

Note

package = editable is the preferred way to enable development/editable mode. See the details in package.

Note

PEP-660 introduced a standardized way of installing a package in development mode, providing the same effect as if pip install -e was used.

⚙️ package 📢 added in 4.0

When option can be one of wheel, sdist, sdist-wheel, editable, editable-legacy, deps-only, skip, or external. If use_develop is set this becomes a constant of editable. If skip_install is set this becomes a constant of skip.

When deps-only is selected, tox installs the package’s dependencies (including any requested extras) but does not build or install the package itself. This is useful for environments that need the same dependencies as the package without the package, such as coverage combining, documentation building, or linting. For projects with static PEP 621 metadata in pyproject.toml, dependencies are read directly without creating a packaging environment. For dynamic dependencies or non-PEP-621 projects, the packaging environment is used to extract metadata.

When sdist-wheel is selected, tox first builds a source distribution and then builds a wheel from that sdist (rather than directly from the source tree). This is useful for verifying that the sdist is complete and that the package can be correctly built from it — catching missing files or packaging errors early.

When editable is selected and the build backend supports PEP 660, tox will use the standardized editable install mechanism. If the backend does not support PEP 660, tox will automatically fall back to editable-legacy mode (equivalent to pip install -e) and print a message suggesting you make this setting explicit in your configuration. To ensure your backend supports the standardized method, verify it meets the minimum version requirement (e.g. setuptools>=64).

⚙️ wheel_build_env with default value of <package_env>-<python-flavor-lowercase><python-version-no-dot> 📢 added in 4.0

If package is set to wheel or sdist-wheel this will be the tox Python environment in which the wheel will be built. For sdist-wheel, the sdist is first built in the package_env environment, then the wheel is built from the extracted sdist in this environment. The value is generated to be unique per Python flavor and version, and prefixed with package_env value. This is to ensure the target interpreter and the generated wheel will be compatible. If you have a wheel that can be reused across multiple Python versions set this value to the same across them (to avoid building a new wheel for each one of them).

⚙️ extras with default value of <empty list> 📢 added in 2.4

A list of “extras” from the package to be installed. For example, extras = testing is equivalent to [testing] in a pip install command.

With package set to deps-only, a self-reference in an extra can select another extra of the same package. A marker on that reference also applies to the dependencies selected through it.

External package builder¶

tox supports operating with externally built packages. External packages might be provided in two ways:

explicitly via the –installpkg CLI argument,
setting the package to external and using a tox packaging environment named <package_env>_external (see package_env) to build the package. The tox packaging environment takes all configuration flags of a python environment, plus the following:

tox rejects a wheel if a .dist-info metadata entry it reads declares more than 8 MiB uncompressed.

⚙️ deps with default value of <empty list> 📢 added in 0.5

Name of the Python dependencies as specified by PEP 440. Installed into the environment prior running the build commands. All installer commands are executed using the tox_root as the current working directory.

⚙️ commands with default value of <empty list> 📢 added in 0.5

Commands to run that will build the package. If any command fails the packaging operation is considered failed and will fail all environments using that package.

⚙️ ignore_errors with default value of False 📢 added in 2.0

When executing the commands keep going even if a sub-command exits with non-zero exit code. The overall status will be “commands failed”, i.e. tox will exit non-zero in case any command failed. It may be helpful to note that this setting is analogous to the -k or --keep-going option of GNU Make.

⚙️ change_dir changedir with default value of {tox_root} 📢 added in 0.5

Change to this working directory when executing the package build command. If the directory does not exist yet, it will be created (required for Windows to be able to execute any command).

⚙️ package_glob with default value of {envtmpdir}{/}dist{/}* 📢 added in 4.0

This pattern selects the wheel or sdist to install. tox resolves a relative pattern against tox_root, including when it starts elsewhere with -c. If the pattern matches zero or multiple files, tox stops packaging with an error.

Python virtual environment¶

⚙️ system_site_packages sitepackages with default value of False 📢 added in 0.8

Create virtual environments that also have access to globally installed packages. Note the default value may be overwritten by the VIRTUALENV_SYSTEM_SITE_PACKAGES environment variable.

Warning

In cases where a command line tool is also installed globally you have to make sure that you use the tool installed in the virtualenv by using python -m <command line tool> (if supported by the tool) or {env_bin_dir}/<command line tool>. If you forget to do that you will get an error.

⚙️ always_copy alwayscopy with default value of False 📢 added in 2.6

Force virtualenv to always copy rather than symlink. Note the default value may be overwritten by the VIRTUALENV_COPIES or VIRTUALENV_ALWAYS_COPY (in that order) environment variables. This is useful for situations where hardlinks don’t work (e.g. running in VMS with Windows guests).

⚙️ download with default value of False 📢 added in 3.10

True if you want virtualenv to upgrade pip/wheel/setuptools to the latest version. Note the default value may be overwritten by the VIRTUALENV_DOWNLOAD environment variable. If (and only if) you want to choose a specific version (not necessarily the latest) then you can add VIRTUALENV_PIP=20.3.3 (and similar) to your set_env.

⚙️ virtualenv_spec with default value of "" 📢 added in 4.42 🔄 changed in 4.56

A PEP 440 version specifier for virtualenv (e.g. virtualenv<20.22.0). When set, tox bootstraps the specified virtualenv version into an isolated environment and drives it via subprocess, instead of using the imported virtualenv library. This enables environments targeting Python versions that are incompatible with the virtualenv installed alongside tox.

Explicit values must name virtualenv with optional version specifiers. pip options, direct references, extras, environment markers, and arbitrary equality (===) are rejected before the bootstrap environment is created.

Left empty (the default), tox derives the value automatically: it inspects the environment’s base_python and, only when the installed virtualenv can no longer create that interpreter, pins the newest virtualenv that still can. The pin is applied for that environment alone, so environments targeting supported Pythons keep using the imported virtualenv with zero overhead. tox downgrades only when every base_python candidate is unsupported by the installed virtualenv – if any candidate would resolve to a creatable interpreter, no pin is applied. Set the value explicitly to override this choice.

The bootstrap environment is cached in .virtualenv-bootstrap/ under work_dir (keyed by a hash of the spec string) and reused across runs. Concurrent access is protected by a file lock. The cache parent must resolve inside work_dir; tox rejects a symlink or Windows junction pointing outside it before opening the lock. On Windows, tox builds the environment under the work directory before moving it into the cache. A junction at the cache entry cannot redirect creation writes. The work directory must allow creating temporary subdirectories. A linked project work directory remains supported.
TOML
[env.legacy]
base_python = ["python3.6"]
virtualenv_spec = "virtualenv<20.22.0"
commands = [["python", "-c", "import sys; print(sys.version)"]]

[env.modern]
base_python = ["python3.15"]
commands = [["python", "-c", "import sys; print(sys.version)"]]
INI (deprecated)
[testenv:legacy]
base_python = python3.6
virtualenv_spec = virtualenv<20.22.0
commands = python -c 'import sys; print(sys.version)'

[testenv:modern]
base_python = python3.15
commands = python -c 'import sys; print(sys.version)'
Changing this value triggers automatic environment recreation (the spec is included in the cache key).

See Virtualenv version pinning for background on when and why to use this setting.

Python virtual environment packaging¶

⚙️ meta_dir with default value of {env_dir}/.meta 📢 added in 4.0.0

Directory where to put the project metadata files.

tox refuses a symlink or Windows junction at this path because the build frontend empties the directory before preparing metadata.

⚙️ pkg_dir with default value of {env_dir}/dist 📢 added in 4.0.0

Directory where to put project packages.

For INI config_settings_* entries, tox reads one key=value pair per line. A substitution inside one pair cannot add another line; a substitution occupying a whole line can supply several pairs.

⚙️ config_settings_get_requires_for_build_sdist 📢 added in 4.11

Config settings (dict[str, str]) passed to the get_requires_for_build_sdist backend API endpoint.

⚙️ config_settings_build_sdist 📢 added in 4.11

Config settings (dict[str, str]) passed to the build_sdist backend API endpoint.

⚙️ config_settings_get_requires_for_build_wheel 📢 added in 4.11

Config settings (dict[str, str]) passed to the get_requires_for_build_wheel backend API endpoint.

⚙️ config_settings_prepare_metadata_for_build_wheel 📢 added in 4.11

Config settings (dict[str, str]) passed to the prepare_metadata_for_build_wheel backend API endpoint.

⚙️ config_settings_build_wheel 📢 added in 4.11

Config settings (dict[str, str]) passed to the build_wheel backend API endpoint.

⚙️ config_settings_get_requires_for_build_editable 📢 added in 4.11

Config settings (dict[str, str]) passed to the get_requires_for_build_editable backend API endpoint.

⚙️ config_settings_prepare_metadata_for_build_editable 📢 added in 4.11

Config settings (dict[str, str]) passed to the prepare_metadata_for_build_editable backend API endpoint.

⚙️ config_settings_build_editable 📢 added in 4.11

Config settings (dict[str, str]) passed to the build_editable backend API endpoint.

⚙️ fresh_subprocess with default value of True if build backend is setuptools otherwise False 📢 added in 4.14.0

A flag controlling if each call to the build backend should be done in a fresh subprocess or not (especially older build backends such as setuptools might require this to discover newly provisioned dependencies).

Pip installer¶

⚙️ install_command with default value of python -I -m pip install {opts} {packages} 📢 added in 1.6

Determines the command used for installing packages into the virtual environment; both the package under test and its dependencies (defined with deps). Must contain the substitution key {packages} which will be replaced by the package(s) to install. You should also accept {opts} – it will contain index server options such as --pre (configured as pip_pre).

Note

You can also provide arbitrary commands to the install_command. Please take care that these commands can be executed on the supported operating systems. When executing shell scripts we recommend to not specify the script directly but instead pass it to the appropriate shell as argument (e.g. prefer bash script.sh over script.sh).

⚙️ list_dependencies_command with default value of python -m pip freeze --all 📢 added in 2.4

The list_dependencies_command setting is used for listing the packages installed into the virtual environment. This command will be executed only if executing on Continuous Integrations is detected (for example set environment variable CI=1) or if journal is active. In TOML configurations, reference this Command value using {replace = "ref"} with extend = true rather than string interpolation.

⚙️ pip_pre with default value of false 📢 added in 1.9

If true, adds --pre to the opts passed to install_command. This will cause it to install the latest available pre-release of any dependencies without a specified version. If false, pip will only install final releases of unpinned dependencies.

⚙️ constrain_package_deps with default value of false 📢 added in 4.4.0

If constrain_package_deps is true, then tox will create and use {env_dir}{/}constraints.txt when installing package dependencies during install_package_deps stage. When this value is set to false, any conflicting package dependencies will override explicit dependencies and constraints passed to deps.

This option has no effect when constraints is set, as the constraints option already applies to package dependency installation.

⚙️ use_frozen_constraints with default value of false 📢 added in 4.4.0

When use_frozen_constraints is true, then tox will use the list_dependencies_command to enumerate package versions in order to create {env_dir}{/}constraints.txt. Otherwise the package specifications explicitly listed under deps (or in requirements / constraints files referenced in deps) will be used as the constraints. pip does not accept extras, editables, local directories or source archives in a constraints file, so tox strips extras and leaves the other three out. If constrain_package_deps is false or constraints is set, then this setting has no effect.

User configuration¶

tox allows creation of user level config-file to modify default values of the CLI commands. It is located in the OS-specific user config directory under tox/config.ini path, see tox --help output for exact location. It can be changed via TOX_USER_CONFIG_FILE environment variable. Example configuration:

[tox]
skip_missing_interpreters = true

Set CLI flags via environment variables¶

Set a CLI option’s default with TOX_<option>. For example, TOX_WORK_DIR sets the default for --workdir; an explicit --workdir flag takes precedence. TOX_OVERRIDE sets the --override option. For options accepting more than one argument, use ; to separate the values.

Relative TOX_INSTALL_PKG and user configuration install_pkg defaults are resolved from the invocation directory, like an explicit --installpkg path.

All configuration inside the configuration file may be overwritten via the TOX_OVERRIDE, note in this case the configuration file and its access (section/table + key) are needed. Here we demonstrate with a tox.ini file:

# set FOO and bar as passed environment variable
$ env 'TOX_OVERRIDE=testenv.pass_env=FOO,BAR' tox c -k pass_env -e py
[testenv:py]
pass_env =
  BAR
  FOO
  <default pass_envs>

# append FOO and bar as passed environment variable to the list already defined in
# the tox configuration
$ env 'TOX_OVERRIDE=testenv.pass_env+=FOO,BAR' tox c -k pass_env -e py
[testenv:py]
pass_env =
  BAR
  FOO
  <pass_envs defined in configuration>
  <default pass_envs>

# set httpx and deps to and 3.12 as base_python
$ env 'TOX_OVERRIDE=testenv.deps=httpx;testenv.base_python=3.12' .tox/dev/bin/tox c \
      -k deps base_python -e py
[testenv:py]
deps = httpx
base_python = 3.12

Factors¶

An environment name is a list of factors joined by -. py313-django50-cov has the factors py313, django50 and cov. One environment section then covers a whole matrix. Combinations of factors decide which environments exist, and each setting picks a value per factor.

Naming¶

Each selected environment name must be one path component. tox rejects . and .., absolute paths, and names containing the platform’s path separators before creating an environment. An empty name in env_list is also rejected.

tox accepts letters, digits, underscores and dots in a factor, so 3.14 and django_5 are both valid. - separates factors and , separates environment names, so a factor contains neither:

[tox]
env_list = 3.14-django50, 3.14-django42, lint

tox compares factors as plain text, so * and ? in a name match nothing.

Implicit factors¶

tox adds two factors to every condition that no environment name contains:

the platform, which sys.platform reports as linux, darwin or win32
the machine architecture, such as arm64 or x86_64, unless the environment name already carries one

[testenv]
deps =
    pytest
    linux: pytest-xvfb

Neither is part of an environment name, so neither can select an environment. tox run -f darwin matches nothing.

Where factors apply¶

A condition applies a setting only in environments containing a factor. INI writes it as a prefix, TOML as a replace = "if" table; Conditional settings and Conditional value reference cover the syntax of each.

Generation creates environments from factor combinations. INI expands braces in env_list and in section names, TOML composes structured dicts; Generative environment list covers both.

Selecting environments by factor¶

-f runs the environments whose name contains the factors you give. Given env_list = 3.14-django50, 3.14-django42, lint:

$ tox run -f django50          # 3.14-django50
$ tox run -f 3.14 django50     # 3.14-django50, since both factors must be present
$ tox run -f django50 -f lint  # 3.14-django50 and lint, since either group will do

Several factors after one -f require all of them; repeating -f accepts any of the groups. Use -e to name environments outright instead.

Pitfalls¶

A condition needs whitespace after its colon. django50: pytest is a condition. django50:pytest is an ordinary value holding a colon, and tox installs a dependency by that name.

In INI, tox also treats a factor named in a condition as an environment name. A [testenv] with docs: sphinx answers to tox run -e docs even when docs appears in no env_list.

TOML only¶

These additional rules are active for native TOML configuration files.

String elements (excluding keys) will be transformed according to the Substitutions section.

String substitution references¶

Added in version 4.21.

Within strings values from other sections can be referred to via {[<table>]<key>}:

which you can use to avoid repetition of config values. You can put default values in one section and reference them in others to avoid repeating the same values:

[extra]
ok = "o"
[env.B]
description = "{[extra]ok}"

If the target table is one of the tox environments variable substitution will be applied on the replaced value, otherwise the text will be inserted as is (e.g., here with extra).

Configuration reference¶

Added in version 4.21.

You can reference other configurations via the ref replacement. This can either be of type:

env, in this case the configuration is loaded from another tox environment, where string substitution will happen in that environments scope:
[env.src] extras = ["A", "{env_name}"] [env.dest] extras = [{ replace = "ref", env = "src", key = "extras", extend = true }, "B"]
In this case dest environments extras will be A, src, B.
raw, in this case the configuration is loaded as raw, and substitution executed in the current environments scope:
[env.src] extras = ["A", "{env_name}"] [env.dest] extras = [{ replace = "ref", of = ["env", "src", "extras"], extend = true }, "B"]
In this case dest environments extras will be A, dest, B.

The extend flag controls if after replacement the value should be replaced as is in the host structure (when flag is false – by default) or be extended into. This flag only operates when the host is a list. A list (or set) result is spread into the host, while a scalar string result is appended as a single element – so a scalar then/else (e.g. then = "-v") adds one item rather than its individual characters, and a false if with no else adds nothing.

An extending replace table cannot also set a nonempty marker. Markers on set_env values remain supported.

When referencing Command-type configuration values (like list_dependencies_command), the reference automatically extracts the command’s argument list, making it compatible with TOML’s structured commands format. For example:

[tool.tox.env.a]
package = "skip"
commands = [[{ replace = "ref", env = "a", key = "list_dependencies_command", extend = true }]]

This expands the Command’s args into the command list, avoiding the need for string interpolation which doesn’t work properly with Command values in TOML.

Positional argument reference¶

Added in version 4.21.

You can reference positional arguments via the posargs replacement:

[env.A]
commands = [["python", { replace = "posargs", default = ["a", "b"], extend = true } ]]

If the positional arguments are not set commands will become python a b, otherwise will be python posarg-set. The extend option instructs tox to unroll the positional arguments within the host structure. Without it the result would become ["python", ["a", "b"] which would be invalid.

Positional arguments are passed through literally by default. Set substitute = true to expand tox substitutions within each argument, such as {env_name} for per-environment report paths:

[env_run_base]
commands = [["pytest", { replace = "posargs", extend = true, substitute = true }]]

For example, tox -e py -- --junitxml=reports/{env_name}.xml passes --junitxml=reports/py.xml to pytest. Each positional argument remains a separate argument, even if its substituted value contains spaces. Substitutions in default values are expanded regardless of this option.

Note that:

[env.A]
commands = [["python", "{posargs}" ]]

Differs in sense that the positional arguments will be set as a single argument, while in the original example they are passed through as separate.

Empty commands groups will be ignored:

[env.A]
commands = [[], ["pytest"]]

will only invoke pytest. This is especially useful together with posargs allowing you to opt out of running a set of commands:

[env.A]
commands = [
    { replace = "posargs", default = ["python", "patch.py"]},
    ["pytest"]
]

When running tox run -e A it will invoke python patch.py followed by pytest. When running tox run -e A -- it will invoke only pytest.

Environment variable reference¶

Added in version 4.21.

You can reference environment variables via the env replacement:

[env.A]
set_env.COVERAGE_FILE = { replace = "env", name = "COVERAGE_FILE", default = "ok" }

If the environment variable is set then the COVERAGE_FILE will become that, otherwise will default to ok.

Inside set_env the table resolves like {env:NAME:DEFAULT}: it reads another set_env key named NAME first, see set_env resolution rules. Naming its own key, as above, reads the host variable.

References within set_env¶

Added in version 4.21.1.

When you want to inherit set_env from another environment you can use the feature that if you pass a list of dictionaries to set_env they will be merged together, for example:

[tool.tox.env_run_base]
set_env = { A = "1", B = "2"}

[tool.tox.env.magic]
set_env = [
    { replace = "ref", of = ["tool", "tox", "env_run_base", "set_env"]},
    { C = "3", D = "4"},
]

Here the magic tox environment will have both A, B, C and D environments set.

When two entries set the same key, the later entry wins. A ref that leads back to itself fails with circular reference and the chain of of paths.

Glob pattern reference¶

Added in version 4.40.

You can expand file system glob patterns via the glob replacement. Matched paths are sorted for deterministic output, and relative patterns are resolved against tox_root. The ** wildcard matches any number of directories recursively.

[env.A]
commands = [["twine", "upload", { replace = "glob", pattern = "dist/*.whl", extend = true }]]

When used with extend = true the matched files are expanded as separate arguments in the host list. Without extend the matches are joined as a single space-separated string.

If no files match and a default is provided it will be used as fallback:

[env.A]
commands = [["twine", "upload", { replace = "glob", pattern = "dist/*.whl", default = ["fallback.whl"], extend = true }]]

When no files match and no default is given, the result is an empty string (or empty list with extend).

pattern and default take substitutions and nested replace tables, as in pattern = "{env_name}/*.whl". Inside set_env the table resolves like {glob:PATTERN:DEFAULT} when the value is read, so {env:NAME} sees the other set_env keys.

Conditional value reference¶

Added in version 4.40: Conditional value replacement with env.VAR lookups.

Changed in version 4.42: Added factor.NAME lookups for environment name factors and platform.

Changed in version 4.50: Added factor['NAME'] and env['VAR'] subscript syntax and env_name variable.

You can conditionally select values based on environment variables and factors via the if replacement. The condition field accepts an expression language that supports env.VAR_NAME lookups for environment variables, factor.NAME lookups for environment name factors and platform, ==/!= comparisons, and and/or/not boolean logic.

Check if an environment variable is set (non-empty):

[env.A]
set_env.MATURITY = { replace = "if", condition = "env.TAG_NAME", then = "production", "else" = "testing" }

If TAG_NAME is set and non-empty, MATURITY becomes production, otherwise testing.

Compare an environment variable to a value:

[env.A]
set_env.MODE = { replace = "if", condition = "env.CI == 'true'", then = "ci", "else" = "local" }

Combine conditions with boolean logic:

[env.A]
set_env.DEPLOY_TARGET = { replace = "if", condition = "env.CI and env.DEPLOY", then = "production", "else" = "none" }

[env.B]
pass_env = [{ replace = "if", condition = "env.CI or env.LOCAL", then = ["AWS_*"], "else" = [], extend = true }]

[env.C]
commands = [["pytest", { replace = "if", condition = "not env.CI", then = ["--pdb"], "else" = [], extend = true }]]

[env.D]
set_env.LOG_LEVEL = { replace = "if", condition = "env.MODE != 'prod'", then = "DEBUG", "else" = "INFO" }

Omitting the else clause defaults to an empty string:

[env.A]
set_env.DEPLOY_FLAG = { replace = "if", condition = "env.DEPLOY", then = "1" }

Nested substitutions in then/else values are processed normally:

[env.A]
set_env.TEST_ENV = { replace = "if", condition = "env.DEPLOY", then = "{env_name}", "else" = "local" }

With extend in list contexts:

[env.A]
commands = [["pytest", { replace = "if", condition = "env.VERBOSE", then = ["--verbose", "--debug"], "else" = ["--quiet"], extend = true }]]

Check if a factor is present:

[env_run_base]
deps = [
    "pytest",
    { replace = "if", condition = "factor.django50", then = ["Django>=5.0,<5.1"], extend = true },
]

If the environment name contains django50 (e.g., py313-django50), the Django dependency is added.

Check for platform factors:

[env_run_base]
commands = [
    { replace = "if", condition = "factor.linux", then = [["pytest", "--numprocesses=auto"]], extend = true },
    { replace = "if", condition = "not factor.linux", then = [["pytest"]], extend = true },
]

The current platform (sys.platform value like linux, darwin, win32) is automatically available as a factor without requiring it in the environment name.

Combine factor conditions with environment variables:

[env_run_base]
commands = [["pytest", { replace = "if", condition = "factor.linux and env.CI", then = ["--numprocesses=auto"], "else" = [], extend = true }]]

Check factors with non-identifier names:

Factor names like 3.14 are not valid Python identifiers, so factor.3.14 would be a syntax error. Use subscript syntax instead:

[env."test-3.14"]
commands = [
    ["pytest", { replace = "if", condition = "factor['3.14']", then = ["--strict-markers"], "else" = [], extend = true }],
]

In this example, the environment name test-3.14 has factors test and 3.14. The subscript syntax also works for environment variables: env['CI'] is equivalent to env.CI.

Check the environment name:

Use env_name to match the full environment name as a string:

[env_run_base]
set_env.CUSTOM_FLAG = { replace = "if", condition = "env_name == 'test-3.14'", then = "enabled", "else" = "" }

Condition expression reference:

env.VAR – value of environment variable VAR (empty string if unset); truthy when non-empty
env['VAR'] – same as env.VAR
factor.NAME – True if NAME is a factor in the environment name or platform; False otherwise
factor['NAME'] – same as factor.NAME, for names that aren’t valid Python identifiers (e.g. 3.14)
env_name – the full environment name as a string
==, != – string comparison
and, or, not – boolean logic
'string' – string literal

INI only¶

These additional rules are active for native INI configuration.

The value for each setting in an INI configuration will be transformed according to the Substitutions section.

Substitution for values from other sections¶

Added in version 1.4.

Values from other sections can be referred to via:

{[sectionname]valuename}

which you can use to avoid repetition of config values. You can put default values in one section and reference them in others to avoid repeating the same values:

[base]
deps =
    pytest
    mock
    pytest-xdist

[testenv:dulwich]
deps =
    dulwich
    {[base]deps}

[testenv:mercurial]
deps =
    mercurial
    {[base]deps}

tox substitutes the referenced value again in the environment that refers to it. Inside set_env, tox pastes the referenced lines as if you wrote them in place and substitutes each value when it reads it, see set_env resolution rules.

In commands, commands_pre and commands_post a reference alone on its line expands to one command per referenced line. A reference that shares its line with other text joins the referenced lines into that command as arguments:

[testenv:lint]
deps =
    ruff
    mypy
commands =
    ruff check .
    mypy src

[testenv:ci]
commands =
    pip install {[testenv:lint]deps}
    {[testenv:lint]commands}

Here ci runs pip install ruff mypy, then ruff check . and mypy src.

Every other list or set setting, such as requires, base_python, pass_env, allowlist_externals or extras, holds one entry per line or, when it has a single line, entries separated by commas. A substitution that is an entry by itself, as in make, {env:MORE_TOOLS}, expands to as many entries as its value holds. One that shares its entry with other text, as in tox-uv=={env:TOX_UV_VERSION}, supplies a part of that one entry, so tox fails when its value contains a line break or, when commas separate the entries, a comma. Text overrides supplied with -x or TOX_OVERRIDE follow the same rule.

Conditional settings¶

Configurations may be set conditionally within the tox.ini file. If a line starts with an environment name or names, separated by a comma, followed by : the configuration will only be used if the environment name(s) matches the executed tox environment. For example:
```
[testenv]
deps =
   pip
   format: black
   py310,py39: pytest
```
Here pip will be always installed as the configuration value is not conditional. black is only used for the format environment, while pytest is only installed for the 3.10 and 3.9 environments.
Negative factors: prefixing a factor name with ! inverts the match – the line is included only when the factor is not present in the environment name:
```
[testenv]
deps =
    !lint: pytest
    !lint: coverage
    lint: ruff
```
Here pytest and coverage are installed for every environment except lint, while ruff is only installed for lint.

Multi-factor conditions with negation: you can combine positive and negative factors:

[testenv]
deps =
    # installed only when both "django" and "mysql" factors are present
    django-mysql: PyMySQL
    # installed for all envs except those with the "slow" factor
    !slow: pytest-timeout
    # installed when either "3.12" or "3.13" factor is present, but not "minimal"
    !minimal-3.12,!minimal-3.13: hypothesis

Factor-conditional commands: factor conditions work in any multi-line setting, not just deps:
```
[testenv]
commands =
    pytest tests
    coverage: coverage report --fail-under=80
```
The coverage report command only runs in environments whose name contains the coverage factor (e.g. 3.13-coverage).
Default fallback: when all lines in a setting are conditional and none match the current environment, the setting falls back to its default value. For example:
```
[testenv]
base_python =
    py312: python3.12
    py313: python3.13
```
If you run an environment named lint (which contains neither the py312 nor py313 factor), base_python falls back to the default – derived from the environment name – rather than becoming an empty string. This applies to any configuration key, not just base_python.

Generative environment list¶

If you have a large matrix of dependencies, python versions and/or environments you can use a generative env_list and conditional settings to express that in a concise form:

TOML

env_list = [
    "lint",
    { product = [
        { prefix = "py3", start = 9, stop = 11 },
        ["django41", "django40"],
        ["sqlite", "mysql"],
    ] },
]

[env_run_base]
deps = [
    { replace = "if", condition = "factor.django41", then = ["Django>=4.1,<4.2"], extend = true },
    { replace = "if", condition = "factor.django40", then = ["Django>=4.0,<4.1"], extend = true },
    { replace = "if", condition = "factor.py311 and factor.mysql", then = ["PyMySQL"], extend = true },
    { replace = "if", condition = "factor.py311 or factor.py310", then = ["urllib3"], extend = true },
    { replace = "if", condition = "(factor.py311 or factor.py310) and factor.sqlite", then = ["mock"], extend = true },
]

INI (deprecated)

[tox]
env_list = py3{9-11}-django{41,40}-{sqlite,mysql}

[testenv]
deps =
    django41: Django>=4.1,<4.2
    django40: Django>=4.0,<4.1
    py311-mysql: PyMySQL
    py311,py310: urllib3
    py{311,310}-sqlite: mock

This will generate the following tox environments (plus lint):

> tox l
default environments:
py39-django41-sqlite  -> [no description]
py39-django41-mysql   -> [no description]
py39-django40-sqlite  -> [no description]
py39-django40-mysql   -> [no description]
py310-django41-sqlite -> [no description]
py310-django41-mysql  -> [no description]
py310-django40-sqlite -> [no description]
py310-django40-mysql  -> [no description]
py311-django41-sqlite -> [no description]
py311-django41-mysql  -> [no description]
py311-django40-sqlite -> [no description]
py311-django40-mysql  -> [no description]

INI expansion syntax¶

Both enumerations ({1,2,3}) and numerical ranges ({1-3}) are supported, and can be mixed together:

[tox]
env_list = py3{8-10, 11, 13-14}

[testenv]
deps =
    py{310,311-314}: urllib3
setenv =
    py{310,311-314}: FOO=bar

will create the following envs:

> tox l
default environments:
py38  -> [no description]
py39  -> [no description]
py310 -> [no description]
py311 -> [no description]
py313 -> [no description]
py314 -> [no description]

Negative ranges will also be expanded ({3-1} -> {3,2,1}). Non-numerical open ranges such as {a-} and {-b} will not be expanded.

A range is recognized only where an environment or a brace item starts, so numbers following a name, a dot or a - stay part of it: py313-django4-2 and py-django-4-2 each name one environment, and 3.10-2 keeps its version. Write py-django-{4-5} for a range after a -. The same rule applies wherever tox reads factors, including -e on the command line.

Open-ended numerical ranges use bounds derived from the supported CPython versions at the time of the tox release:

{10-} expands up to the latest supported CPython minor version (currently 14)
{-13} expands down from the oldest supported CPython minor version (currently 10)

For example, py3{10-} is equivalent to py3{10,11,12,13,14} and py3{-13} is equivalent to py3{10,11,12,13}. These bounds are updated with each tox release as new CPython versions become supported or old ones reach end-of-life.

Caution

Be conscious of the number of significant digits in your range endpoints. A range like py{39-314} will not do what you may expect. (It expands to 275 environment names, py39, py40, py41 … py314.) Instead, use py3{9-14}.

TOML `env_list` item shapes¶

TOML replaces INI’s curly-brace expansion with four structured item shapes. Composition happens through these dicts only — TOML never interprets {...} inside a string item, so a literal "3.{12-14}" is the env name 3.{12-14}, not a range.

Literal string – a single environment name.

env_list = ["lint", "3.12"]

Bare range dict – a single range axis. Accepts prefix, start, and stop. Omit stop to expand up to the latest supported CPython minor version (currently 15), or omit start to expand down from the oldest (currently 10). The bare range dict is equivalent to a single-group product and is the preferred spelling when there is only one axis:

env_list = [
    { prefix = "3.", start = 10 },
    "lint",
]

{ prefix = "3.", start = 10 } is equivalent to 3.{10-} in INI.

Bare labeled dict – a single-key dict mapping a label to a list of factor values. The label also registers for {factor:label} substitution (see Factor label substitution):

env_list = [
    { ecosystem = { values = ["oci", "python"], default = "python" } },
]

[env_run_base]
description = "Sync {factor:ecosystem} artifacts"

[env.lint]

The description is Sync oci artifacts in oci and Sync python artifacts in python. The default also supplies python in environments outside the list, such as lint. Omit default to use an empty string when no factor matches. Bare labeled dicts register their name; numeric labels such as {factor:0} refer to positions in a product or env_base factor list.

Product dict – a Cartesian product of multiple factor groups, joined with -. Each factor group inside product is itself an array of strings, a range dict, or a labeled dict:

env_list = [
    { product = [{ prefix = "3.", start = 12, stop = 14 }, ["django42", "django50"]] },
]

An exclude key removes specific combinations from the product – a capability not available in INI:

env_list = [
    { product = [["3.12", "3.13"], ["django42", "django50"]], exclude = ["3.12-django50"] },
]

Common mistake – wrapping a range or labeled dict inside a list factor group. Factor-group lists may only contain literal strings; range and labeled dicts must appear as sibling entries in the product array, not nested inside one of its arrays. The following is rejected with a clear error:

# wrong — the inner list contains a dict
env_list = [
    { product = [["min"], [{ prefix = "3.", start = 9, stop = 14 }]] },
]

# right — the range dict is a sibling factor group
env_list = [
    { product = [["min"], { prefix = "3.", start = 9, stop = 14 }] },
]

Generative section names¶

Suppose you have some binary packages, and need to run tests both in 32 and 64 bits. You also want an environment to create your virtual env for the developers. This also supports ranges in the same way as generative environment lists.

INI (deprecated)

[testenv]
base_python =
    py311-x86: python3.11-32
    py311-x64: python3.11-64
commands = pytest

[testenv:py311-{x86,x64}-venv]
envdir =
    x86: .venv-x86
    x64: .venv-x64

> tox l
default environments:
py          -> [no description]

additional environments:
py311-x86-venv -> [no description]
py311-x64-venv -> [no description]

TOML

TOML does not support generative section names. Use env_base templates instead:

[env_base.py311-venv]
factors = [["x86", "x64"]]
base_python = { replace = "if", condition = "factor.x86", then = "python3.11-32", "else" = "python3.11-64" }
env_dir = { replace = "if", condition = "factor.x86", then = ".venv-x86", "else" = ".venv-x64" }
commands = [["pytest"]]

This generates py311-venv-x86 and py311-venv-x64, equivalent to the INI generative section.

Substitutions¶

Value substitution operates through the {...} string-substitution pattern. The string inside the curly braces may reference a global or per-environment config key as described above. A brace group is a reference only when its content starts with a key or [section]key. For example, {"url": "https://example.com"} remains text.

tox substitutes a key’s value when it loads the key, then substitutes expressions in referenced configuration text or host environment variables. If nested expansion exceeds the depth limit, tox logs one warning for that value and leaves the remaining references as text. set_env is the exception: tox substitutes each of its values only when it reads that value, see set_env resolution rules.

Positional arguments, file names matched by {glob:PATTERN} and TOX_FACTOR_<label> overrides are data rather than configuration, so tox inserts them as they are: a {...} or [] within them is not a substitution.

In substitutions, the backslash character \ will act as an escape when preceding {, }, :, [, or ], otherwise the backslash will be reproduced literally:

TOML

commands = [
  ["python", "-c", 'print("\{posargs} = \{}".format("{posargs}"))'],
  ["python", "-c", 'print("host: \{}".format("{env:HOSTNAME:host\: not set}")'],
]

INI (deprecated)

commands =
  python -c 'print("\{posargs} = \{}".format("{posargs}"))'
  python -c 'print("host: \{}".format("{env:HOSTNAME:host\: not set}")'

Note that any backslashes remaining after substitution may be processed by shlex during command parsing. On POSIX platforms, the backslash escapes the following character. On Windows, it escapes quotes and other backslashes; backslashes before whitespace remain path separators. UNC prefixes retain their leading pair. Single-quoted text is literal on both platforms.

INI splits a command into arguments after substitution. A path reference such as {tox_root} or {env_tmp_dir} stays within one argument even if it contains spaces, quotes or backslashes. The same applies to tox-provided scalar values such as {host_python} and {tox_root_name}, and to each unquoted entry of a referenced list such as {base_python}. A reference inside a larger word stays in that word, so python {tox_root}{/}scripts{/}report.py needs no extra quotes. A string setting, a key from another section, or an environment variable remains command text when unquoted, so shlex may split it. Within a quoted argument, a substitution stays in that argument even if its value contains quotes or backslashes; for example, "--title={env:TITLE}" remains one argument.

Special substitutions that accept additional colon-delimited : parameters cannot have a space after the : at the beginning of line (e.g. {posargs: magic} would be parsed as factorial {posargs, having value magic).

Environment variable substitutions¶

If you specify a substitution string like this:

{env:KEY}

then the value will be retrieved as os.environ['KEY'] and replaced with an empty string if the environment variable does not exist.

Inside a tox environment, tox looks up KEY in this order:

the environment’s set_env, unless the substitution sits in the value of KEY itself,
the host environment (os.environ),
the default, or an empty string without one.

So commands = echo {env:FOO} prints the set_env value of FOO when the environment sets one.

In an inline deps or constraints entry, a direct {env:NAME} substitution from the host environment keeps ${OTHER} text unchanged when tox builds pip arguments. A TOML replace = "env" table and a TOML reference to the loaded entry retain that behavior. Text supplied by a host variable through set_env does too, including a substitution default. A ${NAME} reference written in the configuration, including a default there, still expands.

Environment variable substitutions with default values¶

If you specify a substitution string like this:

{env:KEY:DEFAULTVALUE}

then the value will be retrieved as os.environ['KEY'] and replaced with DEFAULTVALUE if the environment variable does not exist.

If you specify a substitution string like this:

{env:KEY:}

then the value will be retrieved as os.environ['KEY'] and replaced with an empty string if the environment variable does not exist.

Substitutions can also be nested. In that case they are expanded starting from the innermost expression:

{env:KEY:{env:DEFAULT_OF_KEY}}

the above example is roughly equivalent to os.environ.get('KEY', os.environ['DEFAULT_OF_KEY'])

Interactive shell substitution¶

Added in version 3.4.0.

It’s possible to inject a config value only when tox is running in interactive shell (standard input):

{tty:ON_VALUE:OFF_VALUE}

The first value is the value to inject when the interactive terminal is available, the second value is the value to use when it’s not (optional). A good use case for this is e.g. passing in the --pdb flag for pytest.

Substitutions for positional arguments in commands¶

Added in version 1.0.

If you specify a substitution string like this:

{posargs:DEFAULTS}

then the value will be replaced with positional arguments as provided to the tox command:

tox arg1 arg2

In this instance, the positional argument portion will be replaced with arg1 arg2. If no positional arguments were specified, the value of DEFAULTS will be used instead. If DEFAULTS contains other substitution strings, such as {env:*}, they will be interpreted. The positional arguments themselves are passed through literally, so the command receives {env:HOME} for tox run -- '{env:HOME}'. Only the TOML posargs replacement can opt in to substituting them, with substitute = true.

Use a double -- if you also want to pass options to an underlying test command, for example:

tox run -e 3.14 -- --opt1 ARG1

will make the --opt1 ARG1 appear in all test commands where [] or {posargs} was specified. By default, tox rewrites an existing relative path to keep it pointing at the same entry after change_dir. Bare command names and bare executable first positional values are exceptions described under args_are_paths.

When an INI value uses {posargs}, tox replaces line breaks within each positional argument with spaces before quoting it. INI command and list values use line breaks to separate entries. The same replacement applies to TOML strings containing {posargs}; a TOML replace = "posargs" table keeps line breaks in the argument.

Glob pattern substitution¶

Added in version 4.40.

You can expand glob/wildcard patterns to matching file paths:

{glob:PATTERN}

Matches are sorted and returned as a space-separated string. An unquoted glob substitution in an INI command passes each match as one argument, including file names with blanks or quotes. Quoting the whole substitution joins the matches into one argument. If no files match, the result is an empty string. You can provide a default value for when no files match:

{glob:PATTERN:DEFAULT}

Relative patterns are resolved against tox_root. Use ** for recursive matching across directories.

TOML

[env.A]
commands = [["twine", "upload", "{glob:dist/*.whl}"]]

Or using the TOML dict syntax (see pyproject.toml - native):

[env.A]
commands = [["twine", "upload", { replace = "glob", pattern = "dist/*.whl", extend = true }]]

INI (deprecated)

[testenv]
commands = twine upload {glob:dist/*.whl}
deps = {glob:requirements/*.txt:requirements.txt}

Other substitutions¶

{:} – replaced with os.pathsep (: on POSIX, ; on Windows). Useful for building PATH-like values: set_env = PYTHONPATH={tox_root}/src{:}{tox_root}/lib.
{/} – replaced with os.sep (/ on POSIX, \ on Windows). Useful for cross-platform paths: commands = pytest {tox_root}{/}tests{/}unit.

Substitution quick reference¶

The following table lists all available substitution variables. These can be used as inline replacement objects in TOML or via {name} in INI.

Substitution	Description
`{tox_root}` / `{toxinidir}`	The directory where the configuration file is located (project root).
`{tox_root_name}`	Name of the project root directory (the last path component of `{tox_root}`).
`{home}`	The current user’s home directory.
`{work_dir}` / `{toxworkdir}`	The tox working directory (default: `{tox_root}/.tox`).
`{temp_dir}`	Temporary directory for tox (default: `{work_dir}/.tmp`).
`{env_name}` / `{envname}`	Name of the current tox environment (e.g. `3.13`, `lint`).
`{env_dir}` / `{envdir}`	Directory of the current environment (default: `{work_dir}/{env_name}`).
`{env_tmp_dir}` / `{envtmpdir}`	Temporary directory for the current environment (default: `{env_dir}/tmp`).
`{env_log_dir}` / `{envlogdir}`	Log directory for the current environment (default: `{env_dir}/log`).
`{env_bin_dir}` / `{envbindir}`	Binary directory of the virtual environment (e.g. `{env_dir}/bin`).
`{env_python}` / `{envpython}`	Path to the Python executable in the virtual environment.
`{env_site_packages_dir}` / `{envsitepackagesdir}`	Pure-python site-packages directory (purelib) of the virtual environment.
`{env_site_packages_dir_plat}` / `{envsitepackagesdir_plat}`	Platform-specific site-packages directory (platlib) of the virtual environment.
`{base_python}` / `{basepython}`	The configured base Python interpreter.
`{py_dot_ver}`	Major.Minor version of the environment Python (e.g. `3.14`).
`{py_impl}`	Python implementation name in lowercase (e.g. `cpython`, `pypy`).
`{py_free_threaded}`	`True` if the environment Python is a free-threaded build, else `False`.
`{py_debug}`	`True` if the environment Python is a debug (`Py_DEBUG`) build, else `False`.
`{env:KEY}` / `{env:KEY:DEFAULT}`	Value of environment variable `KEY`, with optional default.
`{posargs}` / `{posargs:DEFAULTS}`	Positional arguments passed after `--`, with optional defaults.
`{tty:ON:OFF}`	`ON` value when running in an interactive terminal, `OFF` otherwise.
`{glob:PATTERN}` / `{glob:PATTERN:DEFAULT}`	Expand glob pattern to matching file paths (space-separated, sorted). Relative paths resolve against `tox_root`.
`{/}`	OS path separator (`/` or `\`).
`{:}`	OS path list separator (`:` or `;`).
`{[section]key}` (INI only)	Value of `key` from `[section]` (cross-section reference).

For TOML-specific replacement syntax (replace = "ref", replace = "posargs", replace = "env", replace = "glob", replace = "if"), see pyproject.toml - native.

Configuration¶

System requirements¶

Discovery and file types¶

Format comparison¶

Environment base templates¶

Factor label substitution¶

tox.ini¶

setup.cfg¶

pyproject.toml - INI¶

pyproject.toml - native¶

tox.toml¶

Core¶

Python language core options¶

tox environment¶

Base options¶

Injected environment variables¶

Execute¶

Run¶

Packaging environment configuration¶

Python options¶

Python run¶

External package builder¶

Python virtual environment¶

Python virtual environment packaging¶

Pip installer¶

User configuration¶

Set CLI flags via environment variables¶

Overriding configuration from the command line¶

Substitutions inside an override¶

Overrides propagate through references¶

Escaping dots in override keys¶

Factors¶

Naming¶

Implicit factors¶

Where factors apply¶

Selecting environments by factor¶

Pitfalls¶

TOML only¶

String substitution references¶

Configuration reference¶

Positional argument reference¶

Environment variable reference¶

References within set_env¶

Glob pattern reference¶

Conditional value reference¶

INI only¶

Substitution for values from other sections¶

Conditional settings¶

Generative environment list¶

INI expansion syntax¶

TOML env_list item shapes¶

Generative section names¶

Substitutions¶

Environment variable substitutions¶

Environment variable substitutions with default values¶

Interactive shell substitution¶

Substitutions for positional arguments in commands¶

Glob pattern substitution¶

Other substitutions¶

Substitution quick reference¶

`tox.ini`¶

`setup.cfg`¶

`pyproject.toml` - INI¶

`pyproject.toml` - native¶

`tox.toml`¶

TOML `env_list` item shapes¶