tox configuration specification

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.

Tox global settings

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

envlist setting

Determining the environment list that tox is to operate one happens in this order:

• command line option -eENVLIST
• environment variable TOXENV
• tox.ini file’s envlist

Virtualenv test environment settings

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:

basepython=NAME-OR-PATH

name or path to a Python interpreter which will be used for creating the virtual environment. default: interpreter used for tox invocation.

commands=ARGVLIST

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.

changedir=path

change to this working directory when executing the test command. default: {toxinidir}

args_are_paths=BOOL

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

envtmpdir=path

defines a temporary directory for the virtualenv which will be cleared each time before the group of test commands is invoked. default: {envdir}/tmp

envlogdir=path

defines a directory for logging where tox will put logs of tool invocation. default: {envdir}/log

deps=MULTI-LINE-LIST

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 usually can be a file, and URL or a package name.

downloadcache=path

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

distribute=True|False

Set to False if you want to use setuptools instead of the default distribute in the virtual environment. default: True.

sitepackages=True|False

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.

Substitutions

Any key=value setting in an ini-file can make use of value substitution through the {...} string-substitution pattern.

Globally available substitutions

{toxinidir}

the directory where tox.ini is located

{toxworkdir}

the directory where virtual environments are created and sub directories for packaging reside.

{homedir}

the user-home directory path.

{distdir}

the directory where sdist-packages will be created in

{distshare}

the directory where sdist-packages will be copied to so that they may be accessed by other processes or tox runs.

substitutions for virtualenv-related sections

{envname}

the name of the virtual environment

{envpython}

path to the virtual Python interpreter

{envdir}

directory of the the virtualenv hierarchy

{envbindir}

directory where executables are located

{envtmpdir}

the environment temporary directory

{envlogdir}

the environment log directory

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.

substitutions for positional arguments in commands

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.

Other Rules and notes

• path specifications: if a specified path is a relative path it will be considered as relative to the toxinidir, the directory where the configuration file resides.