path: root/doc/config.txt

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

.. 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}
         
    **default on environments using python2.5**::

        pip install {opts} {packages}`` 

    this will use pip<1.4 which has no ``--pre`` option.  Note also
    that for python2.5 support you may need to install ssl and/or
    use ``setenv = PIP_INSECURE=1`` in a py25 based testenv.

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

    {defenv:DEFAULTVALUE:KEY}

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

    {defenv::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}



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