tox.ini files uses the standard ConfigParser “ini-style” format. Below you find the specification, but you might want to skim some tox configuration and usage examples first and use this page as a reference.
List of optional global options:
[tox]
toxworkdir=path # tox working directory, defaults to {toxinidir}/.tox
setupdir=path # defaults to {toxinidir}
distdir=path # defaults to {toxworkdir}/dist
distshare=path # defaults to {homedir}/.tox/distshare
envlist=ENVLIST # defaults to the list of all environments
tox autodetects if it is running in a Hudson context (by checking for existence of the HUDSON_URL environment variable) and will first lookup global tox settings in this section:
[tox:hudson]
... # override [tox] settings for the hudson context
# note: for hudson distshare defaults to ``{toxworkdir}/distshare``.
Determining the environment list that tox is to operate one happens in this order:
Test environments are defined by a:
[testenv:NAME]
...
section. The NAME will be the name of the virtual environment. Defaults for each setting in this section are looked up in the:
[testenv]
...
testenvironment default section.
Complete list of settings that you can put into testenv* sections:
name or path to a Python interpreter which will be used for creating the virtual environment. default: interpreter used for tox invocation.
the commands to be called for testing. Each command is defined by one or more lines; a command can have multiple lines if a line ends with the \ character in which case the subsequent line will be appended (and may contain another \ character ...). For eventually performing a call to subprocess.Popen(args, ...) args are determined by splitting the whole command by whitespace.
change to this working directory when executing the test command. default: {toxinidir}
treat positional arguments passed to tox as file system paths and - if they exist on the filesystem - rewrite them according to the changedir. default: True (due to the exists-on-filesystem check it’s usually safe to try rewriting).
defines a temporary directory for the virtualenv which will be cleared each time before the group of test commands is invoked. default: {envdir}/tmp
defines a directory for logging where tox will put logs of tool invocation. default: {envdir}/log
dependencies to be installed into the environment prior to project package installation. Each line defines a dependency, which will be passed to easy_install/pip for processing. It can be a file, and URL or a package name. You can additionally specify an indexserver to use for installing this dependency. All derived dependencies (deps required by the dep) will be loaded from the specified indexserver:
deps = :myindex:pkg
Always recreate virtual environment if this option is True.
(pip only) use this directory for caching downloads - this defaults to the environment variable PIP_DOWNLOAD_CACHE if it is set. default: no download cache will be used. note: if creating multiple environments use of a download cache greatly speeds up the testing process.
Set to False if you want to use setuptools instead of the default distribute in the virtual environment. default: True.
Set to True if you want to create virtual environments that also have access to globally installed packages. default: False, meaning that virtualenvs will be created with --no-site-packages by default.
New in version 0.9.
Multi-line name = URL definitions of python package servers. Depedencies can specify using a specified index server through the :indexservername:depname pattern. The default indexserver definition determines where unscoped dependencies and the sdist install comes from. Example:
[tox]
indexserver =
default = http://mypypi.org
will make tox install all dependencies from this PYPI index server (including when installing the project sdist package).
Any key=value setting in an ini-file can make use of value substitution through the {...} string-substitution pattern.
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.
When you specify positional arguments to a tox run like this:
tox arg1 arg2
these arguments will textually replace the [.*] pattern in any command specification.
Use a double -- if you also want to pass options to an underlying test command, for example:
tox -- --opt1 ARG1
will make the –opt1 ARG1` appear in all test commands where [] 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.