tox: virtualenv-based automation of test activities

home |  install |  examples |  config |  support 

Table Of Contents

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:

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:

...               # 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:


section. The NAME will be the name of the virtual environment. Defaults for each setting in this section are looked up in the:


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:

indexserver =
    default =

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.

Globally available substitutions

the directory where tox.ini is located
the directory where virtual environments are created and sub directories for packaging reside.
the user-home directory path.
the directory where sdist-packages will be created in
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:


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.