quicklinks

home examples
install changelog
config issues[bb]
support

Table Of Contents

Previous topic

Development environment

Next topic

V2: new tox multi-dimensional, platform-specific configuration

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]
minversion=ver    # minimally required tox version
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
skipsdist=BOOL    # defaults to false

tox autodetects if it is running in a Jenkins context (by checking for existence of the JENKINS_URL environment variable) and will first lookup global tox settings in this section:

[tox:jenkins]
...               # override [tox] settings for the jenkins context
# note: for jenkins distshare defaults to ``{toxworkdir}/distshare``.

envlist setting

Determining the environment list that tox is to operate on 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.

install_command=ARGV

New in version 1.6.

WARNING: This setting is EXPERIMENTAL so use with care and be ready to adapt your tox.ini’s with post-1.6 tox releases.

the install_command setting is used for installing packages into the virtual environment; both the package under test and any defined dependencies. Must contain the substitution key {packages} which will be replaced by the packages to install. You should also accept {opts} if you are using pip or easy_install – it will contain index server options if you have configured them via indexserver and the deprecated downloadcache option if you have configured it.

default:

pip install --pre {opts} {packages}
whitelist_externals=MULTI-LINE-LIST

each line specifies a command name (in glob-style pattern format) which can be used in the commands section without triggering a “not installed in virtualenv” warning. Example: if you use the unix make for running tests you can list whitelist_externals=make or whitelist_externals=/usr/bin/make if you want more precision. If you don’t want tox to issue a warning in any case, just use whitelist_externals=* which will match all commands (not recommended).

changedir=path

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

deps=MULTI-LINE-LIST

test-specific dependencies - to be installed into the environment prior to project package installation. Each line defines a dependency, which will be passed to the installer command for processing. Each line specifies a file, a 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 then be retrieved from the specified indexserver:

deps = :myindexserver:pkg

(Experimentally introduced in 1.6.1) all installer commands are executed using the {toxinidir} as the current working directory.

setenv=MULTI-LINE-LIST

New in version 0.9.

each line contains a NAME=VALUE environment variable setting which will be used for all test command invocations as well as for installing the sdist package into a virtual environment.

recreate=True|False(default)

Always recreate virtual environment if this option is True.

downloadcache=path

DEPRECATED – as of August 2013 this option is not very useful because of pypi’s CDN and because of caching pypi server solutions like devpi.

use this directory for caching downloads. This value is overriden by the environment variable PIP_DOWNLOAD_CACHE if it exists. If you specify a custom install_command that uses an installer other than pip, your installer must support the –download-cache command-line option. default: no download cache will be used.

distribute=True|False

DEPRECATED – as of August 2013 you should use setuptools which has merged most of distribute ‘s changes. Just use the default, Luke! In future versions of tox this option might be ignored and setuptools always chosen.

default: False.

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 without inheriting the global site packages.

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

indexserver

New in version 0.9.

Multi-line name = URL definitions of python package servers. Dependencies can specify using a specified index server through the :indexservername:depname pattern. The default indexserver definition determines where unscoped dependencies and the sdist install installs 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).

envdir

New in version 1.5.

User can set specific path for environment. If path would not be absolute it would be treated as relative to {toxinidir}. default: {toxworkdir}/{envname}

usedevelop=BOOL

New in version 1.6.

Install the current package in development mode with “setup.py develop” instead of installing from the sdist package. (This uses pip’s -e option, so should be avoided if you’ve specified a custom install_command that does not support -e).

default: False

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.

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

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

Previous versions of tox supported the [.*] pattern to denote positional arguments with defaults. This format has been deprecated. Use {posargs:DEFAULTS} to specify those.

Substitution for values from other sections

New in version 1.4.

Values from other sections can be refered 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 repeting the same values:

[base]
deps =
    pytest
    mock
    pytest-xdist

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

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

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.