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.
Discovery and file types¶
With regards to the configuration format, at the moment we support the following formats:
Out of box tox supports five configuration locations prioritized in the following order:
tox.ini
(INI),setup.cfg
(INI),pyproject.toml
with thetool.tox
table, havinglegacy_tox_ini
key (containing INI),Native
pyproject.toml
under thetool.tox
table (TOML),tox.toml
(TOML).
Historically, the INI format was created first, and TOML was added in 2024. The TOML format generally is more robust, however is less powerful and more verbose. You should use TOML unless you need some of the more advanced features that TOML does not support (such as conditional factors, generative environments to name a few – however, PRs to add support for these in TOML is welcome).
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]
min_version = 4.20
env_list =
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]
min_version = 4.0
env_list =
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]
min_version = 4.0
env_list =
py310
py39
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.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.11.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.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.11.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
or the [tox:tox]
section of setup.cfg
.
⚙️ requires
with default value of <empty list>
📢 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.
[tool.tox] requires = [ "tox>=4", "virtualenv>20.2", ][tox] requires = tox>=4 virtualenv>20.2
⚙️ min_version
minversion
with default value of <current version of tox>
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.
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>
A list of environments to run by default (when the user does not specify anything during the invocation).
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 keypy27
). Skipped environments will be logged at level two verbosity level.
⚙️ skip_missing_interpreters
with default value of config
📢 added in 1.7.2
Setting this to
true
will forcetox
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. As expected, the command line switch always overrides this setting if passed on the invocation. Setting it toconfig
means that the value is read from the config file.
The root directory for the tox project (where the configuration file is found).
⚙️ work_dir
toxworkdir
with default value of {tox_root}/.tox
Directory for tox to generate its environments into, will be created if it does not exist.
⚙️ temp_dir
with default value of {work_dir}/.tmp
Directory where to put tox temporary files. For example: we create a hard link (if possible, otherwise new copy) in this directory for the project package. This ensures tox works correctly when having parallel runs (as each session will have its own copy of the project package - e.g. the source distribution).
⚙️ no_package
skipsdist
with default value of false
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}
Indicates where the packaging root file exists (historically setup.py file or pyproject.toml now).
⚙️ labels
with default value of <empty dictionary>
A mapping of label names to environments it applies too. For example:
[tool.tox] labels = { test = ["3.13", "3.12"], static = ["ruff", "mypy"] }[tox] labels = test = 3.13, 3.12 static = ruff, mypy
A constant holding the platform of the tox runtime environment.
Python language core options¶
⚙️ ignore_base_python_conflict
ignore_basepython_conflict
with default value of True
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.
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.
tox environment¶
These are configuration for the tox environments (either packaging or run type).
Base options¶
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. If not absolute it would be treated as relative to tox_root.
⚙️ env_tmp_dir
envtmpdir
with default value of {work_dir}/{env_name}/tmp
A folder that is always reset at the start of the run.
⚙️ env_log_dir
envlogdir
with default value of {work_dir}/{env_name}/log
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
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. Runningtox -e <platform_name>
will run commands for a particular platform and skip the rest.
⚙️ pass_env
passenv
with default value of <empty list>
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
ora
will pass through bothA
anda
.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 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
❌
❌
✅
PROGRAMDATA
❌
❌
✅
PROGRAMFILES(x86)
❌
❌
✅
SYSTEMDRIVE
❌
❌
✅
SYSTEMROOT
❌
❌
✅
COMSPEC
❌
❌
✅
PROCESSOR_ARCHITECTURE
❌
❌
✅
NUMBER_OF_PROCESSORS
❌
❌
✅
PIP_*
✅
✅
✅
VIRTUALENV_*
✅
✅
✅
NETRC
✅
✅
✅
More environment variable-related information can be found in Environment variable substitutions.
A dictionary of environment variables to set when running commands in the tox environment. Lines starting with a
file|
prefix define the location of environment file.Note
Environment files are processed using the following rules:
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,
there is no special handling of quotation marks, they are part of the key or value.
More environment variable-related information can be found in Environment variable substitutions.
⚙️ 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
Always recreate virtual environment if this option is true, otherwise leave it up to tox.
⚙️ allowlist_externals
with default value of <empty list>
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
orallowlist_externals=/usr/bin/rm
. If you want to allow all external commands you can useallowlist_externals=*
which will match all commands (not recommended).
⚙️ labels
with default value of <empty list>
A list of labels to apply for this environment. For example:
[tool.tox.env_run_base] labels = ["test", "core"] [tool.tox.env.flake8] labels = ["mypy"][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.
Run¶
⚙️ base
with default value of testenv
📢 added in 4.0.0
Inherit missing keys from these sections.
⚙️ runner
with default value of 📢 added in
4.0.0
The tox execute used to evaluate this environment. Defaults to Python virtual environments, however may be overwritten by plugins.
⚙️ description
with default value of <empty string>
A short description of the environment, this will be used to explain the environment to the user upon listing environments.
⚙️ depends
with default value of <empty list>
tox environments that this environment depends on (must be run after those).
Warning
depends
does not pull in dependencies into the run target, for example if you selectpy310,py39,coverage
via the-e
tox will only run those three (even ifcoverage
may specify asdepends
other targets too - such aspy310, py39, py38
). This is solely meant to specify dependencies and order in between a target run set.
⚙️ commands_pre
with default value of <empty list>
📢 added in 3.4
⚙️ commands
with default value of <empty list>
The commands to be called for testing. Only execute if commands_pre succeed. Each line is interpreted as one command; however a command can be split over multiple lines by ending the line with the
\
character.Commands will execute one by one in sequential fashion until one of them fails (their exit code is non-zero) or all of them succeed. The exit code of a command may be ignored (meaning they are always considered successful) by prefixing the command with a dash (
-
) - this is similar to howmake
recipe lines work. The outcome of the environment is considered successful only if all commands (these + setup + teardown) succeeded (exit code ignored via the-
or success exit code value of zero).Note
The virtual environment binary path (see env_bin_dir) is prepended to the
PATH
environment variable, meaning commands will first try to resolve to an executable from within the virtual environment, and only after that outside of it. Thereforepython
translates as the virtual environmentspython
(having the same runtime version as the base_python), andpip
translates as the virtual environmentspip
.Note
shlex
POSIX-mode quoting rules are used to split the command line into arguments on all supported platforms as of tox 4.4.0.The backslash
\
character can be used to escape quotes, whitespace, itself, and other characters (except on Windows, where a backslash in a path will not be interpreted as an escape). Unescaped single quote will disable the backslash escape until closed by another unescaped single quote. For more details, please see shlex parsing rules.Note
Inline scripts can be used, however note these are discovered from the project root directory, and is not influenced by change_dir (this only affects the runtime current working directory). To make this behavior explicit we recommend that you make inline scripts absolute paths by prepending
{tox_root}
, instead ofpath/to/my_script
prefer{tox_root}{/}path{/}to{/}my_script
. If your inline script is platform dependent refer to Platform specification on how to select different script per platform.
⚙️ commands_post
with default value of <empty list>
Commands to run after running the commands. Execute regardless of the outcome of both commands and commands_pre. All evaluation and configuration logic applies from commands.
⚙️ change_dir
changedir
with default value of {tox_root}
Change to this working directory when executing the test command. If the directory does not exist yet, it will be created (required for Windows to be able to execute any command).
⚙️ args_are_paths
with default value of False
Treat positional arguments passed to tox as file system paths and - if they exist on the filesystem and are in relative format - rewrite them according to the current and change_dir working directory. This handles automatically transforming relative paths specified on the CLI to relative paths respective of the commands executing directory.
⚙️ ignore_errors
with default value of False
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.
⚙️ ignore_outcome
with default value of False
If set to true a failing result of this test environment will not make tox fail (instead just warn).
⚙️ skip_install
with default value of False
📢 added in 1.9
Skip installation of the package. This can be used when you need the virtualenv management but do not want to install the current package into that environment.
⚙️ package_env
with default value of {package_env}
📢 added in 4.0.0
Name of the virtual environment used to create a source distribution from the source tree for this environment.
⚙️ package_tox_env_type
with default value of virtualenv-pep-517
📢 added in 4.0.0
tox package type used to package.
Python options¶
⚙️ base_python
basepython
with default value of <{env_name} python factor> or <python version of tox>
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
meanspython3.10
,py3
meanspython3
andpy
meanspython
. If the name does not match this pattern the same Python version tox is installed into will be used.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.
■ env_site_packages_dir
envsitepackagesdir
The Python environments site package - where packages are installed (the purelib folder path).
The binary folder where console/gui scripts are generated during installation.
The Python executable from within the tox environment.
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.
For example:
[dependency_groups] test = [ "pytest>=8", ] [tool.tox.env_run_base] dependency-groups = [ "test", ][testenv] dependency_groups = test[dependency-groups] test = [ "pytest>=8", ]
⚙️ deps
with default value of <empty list>
Name of the 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),a constraint file when the value starts with
-c
(followed by a file path).If you are only defining PEP 508 requirements (aka no pip requirement files), you should use dependency_groups instead.
- For example:
[tool.tox.env_run_base] deps = [ "pytest>=8", "-r requirements.txt", "-c constraints.txt", ][testenv] deps = pytest>=7,<8 -r requirements.txt -c constraints.txt
⚙️ 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
,editable
,editable-legacy
,skip
, orexternal
. If use_develop is set this becomes a constant ofeditable
. If skip_install is set this becomes a constant ofskip
.
⚙️ 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
this will be the tox Python environment in which the wheel will be built. 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 apip install
command.
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:
⚙️ deps
with default value of <empty list>
⚙️ commands
with default value of <empty list>
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
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}
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{/}*
A glob that should match the wheel/sdist file to install. If no file or multiple files is matched the packaging operation is considered failed and will raise an error.
Python virtual environment¶
⚙️ system_site_packages
sitepackages
with default value of False
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
Force virtualenv to always copy rather than symlink. Note the default value may be overwritten by the
VIRTUALENV_COPIES
orVIRTUALENV_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 addVIRTUALENV_PIP=20.3.3
(and similar) to your set_env.
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.
⚙️ pkg_dir
with default value of {env_dir}/.dist
📢 added in 4.0.0
Directory where to put project packages.
⚙️ config_settings_get_requires_for_build_sdist
📢 added in 4.11
Config settings (
dict[str, str]
) passed to theget_requires_for_build_sdist
backend API endpoint.
⚙️ config_settings_build_sdist
📢 added in 4.11
Config settings (
dict[str, str]
) passed to thebuild_sdist
backend API endpoint.
⚙️ config_settings_get_requires_for_build_wheel
📢 added in 4.11
Config settings (
dict[str, str]
) passed to theget_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 theprepare_metadata_for_build_wheel
backend API endpoint.
⚙️ config_settings_build_wheel
📢 added in 4.11
Config settings (
dict[str, str]
) passed to thebuild_wheel
backend API endpoint.
⚙️ config_settings_get_requires_for_build_editable
📢 added in 4.11
Config settings (
dict[str, str]
) passed to theget_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 theprepare_metadata_for_build_editable
backend API endpoint.
⚙️ config_settings_build_editable
📢 added in 4.11
Config settings (
dict[str, str]
) passed to thebuild_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 aspip_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. preferbash script.sh
overscript.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 variableCI=1
) or if journal is active.
⚙️ pip_pre
with default value of false
📢 added in 1.9
If
true
, adds--pre
to theopts
passed to install_command. This will cause it to install the latest available pre-release of any dependencies without a specified version. Iffalse
, 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 duringinstall_package_deps
stage. When this value is set to false, any conflicting package dependencies will override explicit dependencies and constraints passed todeps
.
⚙️ use_frozen_constraints
with default value of false
📢 added in 4.4.0
When
use_frozen_constraints
is true, then tox will use thelist_dependencies_command
to enumerate package versions in order to create{env_dir}{/}constraints.txt
. Otherwise the package specifications explicitly listed underdeps
(or in requirements / constraints files referenced indeps
) will be used as the constraints. Ifconstrain_package_deps
is false, 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¶
All configuration can be overridden via environment variables too, the naming convention here is TOX_<option>
. E.g.
TOX_WORK_DIR
sets the --workdir
flag, or TOX_OVERRIDE
sets the --override
flag. For flags accepting more
than one argument, use the ;
character to separate these values:
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
Overriding configuration from the command line¶
You can override options in the configuration file, from the command line. For example, given this config:
# tox.toml
[env_run_base]
deps = ["pytest"]
set_env = { foo = "bar" }
commands = [[ "pytest", "tests" ]]
[testenv]
deps = pytest
set_env =
foo=bar
commands = pytest tests
You could enable ignore_errors
by running:
tox --override env_run_base.ignore_errors=True
tox --override testenv.ignore_errors=True
You could add additional dependencies by running:
tox --override env_run_base.deps+=pytest-xdist
tox --override testenv.deps+=pytest-xdist
You could set additional environment variables by running:
tox --override env_run_base.set_env+=baz=quux
tox --override testenv.set_env+=baz=quux
You can specify overrides multiple times on the command line to append multiple items:
tox -x env_run_base.set_env+=foo=bar -x env_run_base.set_env+=baz=quux
tox -x testenv_run_baseenv.deps+=pytest-xdist -x env_run_base.deps+=pytest-covt
tox -x testenv.set_env+=foo=bar -x testenv.set_env+=baz=quux
tox -x testenv.deps+=pytest-xdist -x testenv.deps+=pytest-covt
Or reset override and append to that (note the first override is =
and not +=
):
tox -x env_run_base.deps=pytest-xdist -x env_run_base.deps+=pytest-cov
tox -x testenv.deps=pytest-xdist -x testenv.deps+=pytest-cov
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
environmentsextras
will beA
,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", "extras"], extend = true }, "B"]
In this case
dest
environmentsextras
will beA
,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.
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.
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 the the COVERAGE_FILE
will become that, otherwise will default to ok
.
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.
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}
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, whilepytest
is only installed for thepy310
andpy39
environments.
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:
[tox]
env_list = py{311,310,39}-django{41,40}-{sqlite,mysql}
[testenv]
deps =
django41: Django>=4.1,<4.2
django40: Django>=4.0,<4.1
# use PyMySQL if factors "py311" and "mysql" are present in env name
py311-mysql: PyMySQL
# use urllib3 if any of "py311" or "py310" are present in env name
py311,py310: urllib3
# mocking sqlite on 3.11 and 3.10 if factor "sqlite" is present
py{311,310}-sqlite: mock
This will generate the following tox environments:
> tox l
default environments:
py311-django41-sqlite -> [no description]
py311-django41-mysql -> [no description]
py311-django40-sqlite -> [no description]
py311-django40-mysql -> [no description]
py310-django41-sqlite -> [no description]
py310-django41-mysql -> [no description]
py310-django40-sqlite -> [no description]
py310-django40-mysql -> [no description]
py39-django41-sqlite -> [no description]
py39-django41-mysql -> [no description]
py39-django40-sqlite -> [no description]
py39-django40-mysql -> [no description]
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.
[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:
py310-black -> [no description]
py310-lint -> [no description]
py311-black -> [no description]
py311-lint -> [no description]
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.
In substitutions, the backslash character \
will act as an escape when preceding
{
, }
, :
, [
, or ]
, otherwise the backslash will be reproduced literally:
commands = [
["python", "-c", 'print("\{posargs} = \{}".format("{posargs}"))'],
["python", "-c", 'print("host: \{}".format("{env:HOSTNAME:host\: not set}")'],
]
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 will escape any following character; on windows, the backslash will escape any following quote,
whitespace, or backslash character (since it normally acts as a path delimiter).
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 raise an Error if the environment variable does not exist.
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 replace 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 replace 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.,
Use a double --
if you also want to pass options to an underlying test command, for example:
tox run -e 3.13 -- --opt1 ARG1
will make the --opt1 ARG1
appear in all test commands where []
or {posargs}
was specified. By default (see
args_are_paths
setting), tox
rewrites each positional argument if it is a relative path and exists on the
filesystem to become a path relative to the changedir
setting.
Other Substitutions¶
{}
- replaced asos.pathsep
{/}
- replaced asos.sep