.. be in -*- rst -*- mode!

tox configuration specification
===============================

.. _ConfigParser: http://docs.python.org/library/configparser.html

``tox.ini`` files uses the standard ConfigParser_ "ini-style" format.
Below you find the specification, but you might want to skim some
:doc:`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``.

.. confval:: skip_missing_interpreters=BOOL

    .. versionadded:: 1.7.2

    Setting this to ``True`` is equivalent of passing the
    ``--skip-missing-interpreters`` command line option, and will force ``tox`` to
    return success even if some of the specified environments were missing. This is
    useful for some CI systems or 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 invokation.
    **Default:** ``False``

.. confval:: envlist=CSV

    Determining the environment list that ``tox`` is to operate on
    happens in this order (if any is found, no further lookups are made):

    * 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:

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

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

.. confval:: install_command=ARGV

    .. versionadded:: 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 :confval:`indexserver`
    and the deprecated :confval:`downloadcache` option
    if you have configured it.

    **default**::

        pip install --pre {opts} {packages}

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

.. confval:: changedir=path

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

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

.. confval:: setenv=MULTI-LINE-LIST

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

.. confval:: recreate=True|False(default)

    Always recreate virtual environment if this option is True.

.. confval:: 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 <http://doc.devpi.net>`_.

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

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

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

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

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

.. confval:: envlogdir=path

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

.. confval:: indexserver

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


.. confval:: envdir

   .. versionadded:: 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}``

.. confval:: usedevelop=BOOL

    .. versionadded:: 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 :confval:`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.

substitutions for virtualenv-related sections
+++++++++++++++++++++++++++++++++++++++++++++

``{envname}``
    the name of the virtual environment
``{envpython}``
    path to the virtual Python interpreter
``{envdir}``
    directory of the virtualenv hierarchy
``{envbindir}``
    directory where executables are located
``{envsitepackagesdir}``
    directory where packages are installed.
    Note that architecture-specific files may appear in a different directory.
``{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.


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 and empty string if the environment variable does not
exist.

.. _`command positional substitution`:
.. _`positional substitution`:

substitutions for positional arguments in commands
++++++++++++++++++++++++++++++++++++++++++++++++++

.. versionadded:: 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
+++++++++++++++++++++++++++++++++++++++++++

.. versionadded:: 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}


Generating environments, conditional settings
---------------------------------------------

.. versionadded:: 1.8

Suppose you want to test your package against python2.6, python2.7 and against
several versions of a dependency, say Django 1.5 and Django 1.6. You can
accomplish that by writing down 2*2 = 4 ``[testenv:*]`` sections and then
listing all of them in ``envlist``.

However, a better approach looks like this::

    [tox]
    envlist = {py26,py27}-django{15,16}

    [testenv]
    basepython =
        py26: python2.6
        py27: python2.7
    deps =
        pytest
        django15: Django>=1.5,<1.6
        django16: Django>=1.6,<1.7
        py26: unittest2
    commands = py.test

This uses two new facilities of tox-1.8:

- generative envlist declarations where each envname
  consists of environment parts or "factors"

- "factor" specific settings

Let's go through this step by step.


Generative envlist
+++++++++++++++++++++++

::

    envlist = {py26,py27}-django{15,16}

This is bash-style syntax and will create ``2*2=4`` environment names
like this::

    py26-django15
    py26-django16
    py27-django15
    py27-django16

You can still list environments explicitly along with generated ones::

    envlist = {py26,py27}-django{15,16}, docs, flake

.. note::

    To help with understanding how the variants will produce section values,
    you can ask tox to show their expansion with a new option::

        $ tox -l
        py26-django15
        py26-django16
        py27-django15
        py27-django16
        docs
        flake


Factors and factor-conditional settings
++++++++++++++++++++++++++++++++++++++++

Parts of an environment name delimited by hyphens are called factors and can
be used to set values conditionally::

    basepython =
        py26: python2.6
        py27: python2.7

This conditional setting will lead to either ``python2.6`` or
``python2.7`` used as base python, e.g. ``python2.6`` is selected if current
environment contains ``py26`` factor.

In list settings such as ``deps`` or ``commands`` you can freely intermix
optional lines with unconditional ones::

    deps =
        pytest
        django15: Django>=1.5,<1.6
        django16: Django>=1.6,<1.7
        py26: unittest2

Reading it line by line:

- ``pytest`` will be included unconditionally,
- ``Django>=1.5,<1.6`` will be included for environments containing ``django15`` factor,
- ``Django>=1.6,<1.7`` similarly depends on ``django16`` factor,
- ``unittest`` will be loaded for Python 2.6 environments.

.. note::

    Tox provides good defaults for basepython setting, so the above
    ini-file can be further reduced by omitting the ``basepython``
    setting.


Complex factor conditions
+++++++++++++++++++++++++

Sometimes you need to specify same line for several factors or create a special
case for a combination of factors. Here is how you do it::

    [tox]
    envlist = py{26,27,33}-django{15,16}-{sqlite,mysql}

    [testenv]
    deps =
        py33-mysql: PyMySQL     ; use if both py33 and mysql are in an env name
        py26,py27: urllib3      ; use if any of py26 or py27 are in an env name
        py{26,27}-sqlite: mock  ; mocking sqlite in python 2.x

Take a look at first ``deps`` line. It shows how you can special case something
for a combination of factors, you just join combining factors with a hyphen.
This particular line states that ``PyMySQL`` will be loaded for python 3.3,
mysql environments, e.g. ``py33-django15-mysql`` and ``py33-django16-mysql``.

The second line shows how you use same line for several factors - by listing
them delimited by commas. It's possible to list not only simple factors, but
also their combinations like ``py26-sqlite,py27-sqlite``.

Finally, factor expressions are expanded the same way as envlist, so last
example could be rewritten as ``py{26,27}-sqlite``.

.. note::

    Factors don't do substring matching against env name, instead every
    hyphenated expression is split by ``-`` and if ALL the factors in an
    expression are also factors of an env then that condition is considered
    hold.

    For example, environment ``py26-mysql``:

    - could be matched with expressions ``py26``, ``py26-mysql``,
      ``mysql-py26``,
    - but not with ``py2`` or ``py26-sql``.


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.

.. include:: links.txt