Welcome to the tox automation project

Vision: standardize testing in Python

tox aims to automate and standardize testing in Python. It is part of a larger vision of easing the packaging, testing and release process of Python software.

What is tox?

tox is a generic virtualenv management and test command line tool you can use for:

• checking that your package installs correctly with different Python versions and interpreters

• running your tests in each of the environments, configuring your test tool of choice

• acting as a frontend to Continuous Integration servers, greatly reducing boilerplate and merging CI and shell-based testing.

Basic example

First, install tox with pip install tox. Then put basic information about your project and the test environments you want your project to run in into a tox.ini file residing right next to your setup.py file:

# content of: tox.ini , put in same dir as setup.py
[tox]
envlist = py27,py36

[testenv]
# install pytest in the virtualenv where commands will be executed
deps = pytest
commands =
    # NOTE: you can run any command line tool here - not just tests
    pytest

You can also try generating a tox.ini file automatically, by running tox-quickstart and then answering a few simple questions.

To sdist-package, install and test your project against Python2.7 and Python3.6, just type:

tox

and watch things happen (you must have python2.7 and python3.6 installed in your environment otherwise you will see errors). When you run tox a second time you’ll note that it runs much faster because it keeps track of virtualenv details and will not recreate or re-install dependencies. You also might want to checkout tox configuration and usage examples to get some more ideas.

System overview

tox workflow diagram

tox roughly follows the following phases:

1. configuration: load tox.ini and merge it with options from the command line and the operating system environment variables.

2. packaging (optional): create a source distribution of the current project by invoking

   python setup.py sdist
   

   Note that for this operation the same Python environment will be used as the one tox is installed into (therefore you need to make sure that it contains your build dependencies). Skip this step for application projects that don’t have a setup.py.

3. environment - for each tox environment (e.g. py27, py36) do:

   1. environment creation: create a fresh environment, by default virtualenv is used. tox will automatically try to discover a valid Python interpreter version by using the environment name (e.g. py27 means Python 2.7 and the basepython configuration value) and the current operating system PATH value. This is created at first run only to be re-used at subsequent runs. If certain aspects of the project change, a re-creation of the environment is automatically triggered. To force the recreation tox can be invoked with -r/--recreate.

   2. install (optional): install the environment dependencies specified inside the deps configuration section, and then the earlier packaged source distribution. By default pip is used to install packages, however one can customise this via install_command. Note pip will not update project dependencies (specified either in the install_requires or the extras section of the setup.py) if any version already exists in the virtual environment; therefore we recommend to recreate your environments whenever your project dependencies change.

   3. commands: run the specified commands in the specified order. Whenever the exit code of any of them is not zero stop, and mark the environment failed. Note, starting a command with a single dash character means ignore exit code.

4. report print out a report of outcomes for each tox environment:

   ____________________ summary ____________________
   py27: commands succeeded
   ERROR:   py36: commands failed
   

   Only if all environments ran successfully tox will return exit code 0 (success). In this case you’ll also see the message congratulations :).

tox will take care of environment isolation for you: it will strip away all operating system environment variables not specified via passenv. Furthermore, it will also alter the PATH variable so that your commands resolve first and foremost within the current active tox environment. In general all executables in the path are available in commands, but tox will emit a warning if it was not explicitly allowed via allowlist_externals.

Current features

• automation of tedious Python related test activities

• test your Python package against many interpreter and dependency configs

  • automatic customizable (re)creation of virtualenv test environments

  • installs your setup.py based project into each virtual environment

  • test-tool agnostic: runs pytest, nose or unittests in a uniform manner

• plugin system to modify tox execution with simple hooks.

• uses pip and setuptools by default. Support for configuring the installer command through install_command=ARGV.

• cross-Python compatible: CPython-2.7, 3.5 and higher, Jython and pypy.

• cross-platform: Windows and Unix style environments

• integrates with continuous integration servers like Jenkins (formerly known as Hudson) and helps you to avoid boilerplatish and platform-specific build-step hacks.

• full interoperability with devpi: is integrated with and is used for testing in the devpi system, a versatile PyPI index server and release managing tool.

• driven by a simple ini-style config file

• documented examples and configuration

• concise reporting about tool invocations and configuration errors

• professionally supported

• supports using different / multiple PyPI index servers

Related projects

tox has influenced several other projects in the Python test automation space. If tox doesn’t quite fit your needs or you want to do more research, we recommend taking a look at these projects:

• Invoke is a general-purpose task execution library, similar to Make. Invoke is far more general-purpose than tox but it does not contain the Python testing-specific features that tox specializes in.

• Nox is a project similar in spirit to tox but different in approach. Nox’s key difference is that it uses Python scripts instead of a configuration file. Nox might be useful if you find tox’s configuration too limiting but aren’t looking to move to something as general-purpose as Invoke or Make.

tox installation

Install info in a nutshell

Pythons: CPython 2.7 and 3.5 or later, Jython-2.5.1, pypy-1.9ff

Operating systems: Linux, Windows, OSX, Unix

Installer Requirements: setuptools

License: MIT license

git repository: https://github.com/tox-dev/tox

Installation with pip

Use the following command:

pip install tox

It is fine to install tox itself into a virtualenv environment.

Install from clone

Consult the GitHub page how to clone the git repository:

https://github.com/tox-dev/tox

and then install in your environment with something like:

$ cd <path/to/clone>
$ pip install .

or install it editable if you want code changes to propagate automatically:

$ cd <path/to/clone>
$ pip install --editable .

so that you can do changes and submit patches.

[Linux/macOS] Install via your package manager

You can also find tox packaged for many Linux distributions and Homebrew for macOs - usually under the name of python-tox or simply tox. Be aware though that there also other projects under the same name (most prominently a secure chat client with no affiliation to this project), so make sure you install the correct package.

tox configuration and usage examples

Basic usage

A simple tox.ini / default environments

Put basic information about your project and the test environments you want your project to run in into a tox.ini file that should reside next to your setup.py file:

# content of: tox.ini , put in same dir as setup.py
[tox]
envlist = py27,py36
[testenv]
# install testing framework
# ... or install anything else you might need here
deps = pytest
# run the tests
# ... or run any other command line tool you need to run here
commands = pytest

To sdist-package, install and test your project, you can now type at the command prompt:

tox

This will sdist-package your current project, create two virtualenv Environments, install the sdist-package into the environments and run the specified command in each of them. With:

tox -e py36

you can restrict the test run to the python3.6 environment.

Tox currently understands the following patterns:

py: The current Python version tox is using
pypy: Whatever available PyPy there is
jython: Whatever available Jython there is
pyN: Python of version N. for example py2 or py3 ... etc
pyNM: Python of version N.M. for example py27 or py38 ... etc
pypyN: PyPy of version N. for example pypy2 or pypy3 ... etc
pypyNM: PyPy version N.M. for example pypy27 or pypy35 ... etc

However, you can also create your own test environment names, see some of the examples in examples.

pyproject.toml tox legacy ini

The tox configuration can also be in pyproject.toml (if you want to avoid an extra file).

Currently only the old format is supported via legacy_tox_ini, a native implementation is planned though.

[build-system]
requires = [ "setuptools >= 35.0.2", "wheel >= 0.29.0"]
build-backend = "setuptools.build_meta"

[tool.tox]
legacy_tox_ini = """
[tox]
envlist = py27,py36

[testenv]
deps = pytest >= 3.0.0, <4
commands = pytest
"""

Note that when you define a pyproject.toml you must define the build-system section per PEP-518.

Specifying a platform

New in version 2.0.

If you want to specify which platform(s) your test environment runs on you can set a platform regular expression like this:

[testenv]
platform = linux2|darwin

If the expression does not match against sys.platform the test environment will be skipped.

Allowing non-virtualenv commands

New in version 1.5.

Sometimes you may want to use tools not contained in your virtualenv such as make, bash or others. To avoid warnings you can use the allowlist_externals testenv configuration:

# content of tox.ini
[testenv]
allowlist_externals = make
                      /bin/bash

Depending on requirements.txt or defining constraints

New in version 1.6.1.

(experimental) If you have a requirements.txt file or a constraints.txt file you can add it to your deps variable like this:

[testenv]
deps = -rrequirements.txt

or

[testenv]
deps =
    -rrequirements.txt
    -cconstraints.txt

All installation commands are executed using {toxinidir} (the directory where tox.ini resides) as the current working directory. Therefore, the underlying pip installation will assume requirements.txt or constraints.txt to exist at {toxinidir}/requirements.txt or {toxinidir}/constraints.txt.

This is actually a side effect that all elements of the dependency list is directly passed to pip.

For more details on requirements.txt files or constraints.txt files please see:

• https://pip.pypa.io/en/stable/user_guide/#requirements-files

• https://pip.pypa.io/en/stable/user_guide/#constraints-files

Using a different default PyPI URL

To install dependencies and packages from a different default PyPI server you can type interactively:

tox -i https://pypi.my-alternative-index.org

This causes tox to install dependencies and the sdist install step to use the specified URL as the index server.

You can cause the same effect by using a PIP_INDEX_URL environment variable. This variable can be also set in tox.ini:

[testenv]
setenv =
    PIP_INDEX_URL = https://pypi.my-alternative-index.org

Alternatively, a configuration where PIP_INDEX_URL could be overriden from environment:

[testenv]
setenv =
    PIP_INDEX_URL = {env:PIP_INDEX_URL:https://pypi.my-alternative-index.org}

Installing dependencies from multiple PyPI servers

You can instrument tox to install dependencies from multiple PyPI servers, using PIP_EXTRA_INDEX_URL environment variable:

[testenv]
setenv =
    PIP_EXTRA_INDEX_URL = https://mypypiserver.org
deps =
    # docutils will be installed directly from PyPI
    docutils
    # mypackage missing at PyPI will be installed from custom PyPI URL
    mypackage

This configuration will install docutils from the default Python PyPI server and will install the mypackage from our index server at https://mypypiserver.org URL.

Warning

Using an extra PyPI index for installing private packages may cause security issues. For example, if mypackage is registered with the default PyPI index, pip will install mypackage from the default PyPI index, not from the custom one.

Further customizing installation

New in version 1.6.

By default tox uses pip to install packages, both the package-under-test and any dependencies you specify in tox.ini. You can fully customize tox’s install-command through the testenv-specific install_command=ARGV setting. For instance, to use pip’s --find-links and --no-index options to specify an alternative source for your dependencies:

[testenv]
install_command = pip install --pre --find-links https://packages.example.com --no-index {opts} {packages}

Forcing re-creation of virtual environments

New in version 0.9.

To force tox to recreate a (particular) virtual environment:

tox --recreate -e py27

would trigger a complete reinstallation of the existing py27 environment (or create it afresh if it doesn’t exist).

Passing down environment variables

New in version 2.0.

By default tox will only pass the PATH environment variable (and on windows SYSTEMROOT and PATHEXT) from the tox invocation to the test environments. If you want to pass down additional environment variables you can use the passenv option:

[testenv]
passenv = LANG

When your test commands execute they will execute with the same LANG setting as the one with which tox was invoked.

Setting environment variables

New in version 1.0.

If you need to set an environment variable like PYTHONPATH you can use the setenv directive:

[testenv]
setenv = PYTHONPATH = {toxinidir}/subdir

When your test commands execute they will execute with a PYTHONPATH setting that will lead Python to also import from the subdir below the directory where your tox.ini file resides.

Special handling of PYTHONHASHSEED

New in version 1.6.2.

By default, tox sets PYTHONHASHSEED for test commands to a random integer generated when tox is invoked. This mimics Python’s hash randomization enabled by default starting in Python 3.3. To aid in reproducing test failures, tox displays the value of PYTHONHASHSEED in the test output.

You can tell tox to use an explicit hash seed value via the --hashseed command-line option to tox. You can also override the hash seed value per test environment in tox.ini as follows:

[testenv]
setenv = PYTHONHASHSEED = 100

If you wish to disable this feature, you can pass the command line option --hashseed=noset when tox is invoked. You can also disable it from the tox.ini by setting PYTHONHASHSEED = 0 as described above.

Integration with “setup.py test” command

Warning

setup.py test is deprecated and will be removed in a future version.

Ignoring a command exit code

In some cases, you may want to ignore a command exit code. For example:

[testenv:py27]
commands = coverage erase
       {envbindir}/python setup.py develop
       coverage run -p setup.py test
       coverage combine
       - coverage html
       {envbindir}/flake8 loads

By using the - prefix, similar to a make recipe line, you can ignore the exit code for that command.

Compressing dependency matrix

If you have a large matrix of dependencies, python versions and/or environments you can use Generative envlist and conditional settings to express that in a concise form:

[tox]
envlist = py{36,37,38}-django{22,30}-{sqlite,mysql}

[testenv]
deps =
    django22: Django>=2.2,<2.3
    django30: Django>=3.0,<3.1
    # use PyMySQL if factors "py37" and "mysql" are present in env name
    py38-mysql: PyMySQL
    # use urllib3 if any of "py36" or "py37" are present in env name
    py36,py37: urllib3
    # mocking sqlite on 3.6 and 3.7 if factor "sqlite" is present
    py{36,37}-sqlite: mock

Using generative section names

Suppose you have some binary packages, and need to run tests both in 32 and 64 bits. You also want an environment to create your virtual env for the developers.

[testenv]
basepython =
    py38-x86: python3.8-32
    py38-x64: python3.8-64
commands = pytest

[testenv:py38-{x86,x64}-venv]
usedevelop = true
envdir =
    x86: .venv-x86
    x64: .venv-x64
commands =

Prevent symbolic links in virtualenv

By default virtualenv will use symlinks to point to the system’s python files, modules, etc. If you want the files to be copied instead, possibly because your filesystem is not capable of handling symbolic links, you can instruct virtualenv to use the “–always-copy” argument meant exactly for that purpose, by setting the alwayscopy directive in your environment:

[testenv]
alwayscopy = True

Parallel mode

tox allows running environments in parallel:

• Invoke by using the --parallel or -p flag. After the packaging phase completes tox will run in parallel processes tox environments (spins a new instance of the tox interpreter, but passes through all host flags and environment variables).

• -p takes an argument specifying the degree of parallelization, defaulting to auto:

  • all to run all invoked environments in parallel,

  • auto to limit it to CPU count,

  • or pass an integer to set that limit.

• Parallel mode displays a progress spinner while running tox environments in parallel, and reports outcome of these as soon as completed with a human readable duration timing attached. This spinner can be disabled by setting the environment variable TOX_PARALLEL_NO_SPINNER to the value 1.

• Parallel mode by default shows output only of failed environments and ones marked as parallel_show_output =True.

• There’s now a concept of dependency between environments (specified via depends), tox will re-order the environment list to be run to satisfy these dependencies (in sequential run too). Furthermore, in parallel mode, will only schedule a tox environment to run once all of its dependencies finished (independent of their outcome).

  Warning

  depends does not pull in dependencies into the run target, for example if you select py27,py36,coverage via the -e tox will only run those three (even if coverage may specify as depends other targets too - such as py27, py35, py36, py37).

• --parallel-live/-o allows showing the live output of the standard output and error, also turns off reporting described above.

• Note: parallel evaluation disables standard input. Use non parallel invocation if you need standard input.

Example final output:

$ tox -e py27,py36,coverage -p all
✔ OK py36 in 9.533 seconds
✔ OK py27 in 9.96 seconds
✔ OK coverage in 2.0 seconds
___________________________ summary ______________________________________________________
  py27: commands succeeded
  py36: commands succeeded
  coverage: commands succeeded
  congratulations :)

Example progress bar, showing a rotating spinner, the number of environments running and their list (limited up to 120 characters):

⠹ [2] py27 | py36

tox auto-provisioning

In case the host tox does not satisfy either the minversion or the requires, tox will now automatically create a virtual environment under provision_tox_env that satisfies those constraints and delegate all calls to this meta environment. This should allow automatically satisfying constraints on your tox environment, given you have at least version 3.8.0 of tox.

For example given:

[tox]
minversion = 3.10.0
requires = tox_venv >= 1.0.0

if the user runs it with tox 3.8.0 or later installed tox will automatically ensured that both the minimum version and requires constraints are satisfied, by creating a virtual environment under .tox folder, and then installing into it tox >= 3.10.0 and tox_venv >= 1.0.0. Afterwards all tox invocations are forwarded to the tox installed inside .tox\.tox folder (referred to as meta-tox or auto-provisioned tox).

This allows tox to automatically setup itself with all its plugins for the current project. If the host tox satisfies the constraints expressed with the requires and minversion no such provisioning is done (to avoid setup cost when it’s not explicitly needed).

Packaging

Although one can use tox to develop and test applications one of its most popular usage is to help library creators. Libraries need first to be packaged, so then they can be installed inside a virtual environment for testing. To help with this tox implements PEP-517 and PEP-518. This means that by default tox will build source distribution out of source trees. Before running test commands pip is used to install the source distribution inside the build environment.

To create a source distribution there are multiple tools out there and with PEP-517 and PEP-518 you can easily use your favorite one with tox. Historically tox only supported setuptools, and always used the tox host environment to build a source distribution from the source tree. This is still the default behavior. To opt out of this behaviour you need to set isolated builds to true.

setuptools

Using the pyproject.toml file at the root folder (alongside setup.py) one can specify build requirements.

[build-system]
requires = [
    "setuptools >= 35.0.2",
    "setuptools_scm >= 2.0.0, <3"
]
build-backend = "setuptools.build_meta"

# tox.ini
[tox]
isolated_build = True

flit

flit requires Python 3, however the generated source distribution can be installed under python 2. Furthermore it does not require a setup.py file as that information is also added to the pyproject.toml file.

[build-system]
requires = ["flit_core >=2,<4"]
build-backend = "flit_core.buildapi"

[tool.flit.metadata]
module = "package_toml_flit"
author = "Happy Harry"
author-email = "happy@harry.com"
home-page = "https://github.com/happy-harry/is"

# tox.ini
[tox]
isolated_build = True

poetry

poetry requires Python 3, however the generated source distribution can be installed under python 2. Furthermore it does not require a setup.py file as that information is also added to the pyproject.toml file.

[build-system]
requires = ["poetry_core>=1.0.0"]
build-backend = "poetry.core.masonry.api"

[tool.poetry]
name = "package_toml_poetry"
version = "0.1.0"
description = ""
authors = ["Name <email@email.com>"]

# tox.ini
[tox]
isolated_build = True

[tox:.package]
# note tox will use the same python version as under what tox is installed to package
# so unless this is python 3 you can require a given python version for the packaging
# environment via the basepython key
basepython = python3

pytest and tox

It is easy to integrate pytest runs with tox. If you encounter issues, please check if they are listed as a known issue and/or use the support channels.

Basic example

Assuming the following layout:

tox.ini      # see below for content
setup.py     # a classic distutils/setuptools setup.py file

and the following tox.ini content:

[tox]
envlist = py35,py36

[testenv]
deps = pytest               # PYPI package providing pytest
commands = pytest {posargs} # substitute with tox' positional arguments

you can now invoke tox in the directory where your tox.ini resides. tox will sdist-package your project, create two virtualenv environments with the python3.5 and python3.6 interpreters, respectively, and will then run the specified test command in each of them.

Extended example: change dir before test and use per-virtualenv tempdir

Assuming the following layout:

tox.ini      # see below for content
setup.py     # a classic distutils/setuptools setup.py file
tests        # the directory containing tests

and the following tox.ini content:

[tox]
envlist = py35,py36

[testenv]
changedir = tests
deps = pytest
# change pytest tempdir and add posargs from command line
commands = pytest --basetemp="{envtmpdir}" {posargs}

you can invoke tox in the directory where your tox.ini resides. Differently than in the previous example the pytest command will be executed with a current working directory set to tests and the test run will use the per-virtualenv temporary directory.

Using multiple CPUs for test runs

pytest supports distributing tests to multiple processes and hosts through the pytest-xdist plugin. Here is an example configuration to make tox use this feature:

[testenv]
deps = pytest-xdist
changedir = tests
# use three sub processes
commands = pytest --basetemp="{envtmpdir}"  \
                  --confcutdir=..         \
                  -n 3                    \
                  {posargs}

Known issues and limitations

Too long filenames. you may encounter “too long filenames” for temporarily created files in your pytest run. Try to not use the “–basetemp” parameter.

installed-versus-checkout version. pytest collects test modules on the filesystem and then tries to import them under their fully qualified name. This means that if your test files are importable from somewhere then your pytest invocation may end up importing the package from the checkout directory rather than the installed package.

This issue may be characterised by pytest test-collection error messages, in python 3.x environments, that look like:

import file mismatch:
imported module 'myproj.foo.tests.test_foo' has this __file__ attribute:
  /home/myuser/repos/myproj/build/lib/myproj/foo/tests/test_foo.py
which is not the same as the test file we want to collect:
  /home/myuser/repos/myproj/myproj/foo/tests/test_foo.py
HINT: remove __pycache__ / .pyc files and/or use a unique basename for your test file modules

There are a few ways to prevent this.

With installed tests (the tests packages are known to setup.py), a safe and explicit option is to give the explicit path {envsitepackagesdir}/mypkg to pytest. Alternatively, it is possible to use changedir so that checked-out files are outside the import path, then pass --pyargs mypkg to pytest.

With tests that won’t be installed, the simplest way to run them against your installed package is to avoid __init__.py files in test directories; pytest will still find and import them by adding their parent directory to sys.path but they won’t be copied to other places or be found by Python’s import system outside of pytest.

unittest2, discover and tox

Running unittests with ‘discover’

The discover project allows you to discover and run unittests that you can easily integrate it in a tox run. As an example, perform a checkout of Pygments:

hg clone https://bitbucket.org/birkenfeld/pygments-main

and add the following tox.ini to it:

[tox]
envlist = py27,py35,py36

[testenv]
changedir = tests
commands = discover
deps = discover

If you now invoke tox you will see the creation of three virtual environments and a unittest-run performed in each of them.

Running unittest2 and sphinx tests in one go

Michael Foord has contributed a tox.ini file that allows you to run all tests for his mock project, including some sphinx-based doctests. If you checkout its repository with:

git clone https://github.com/testing-cabal/mock.git

The checkout has a tox.ini file that looks like this:

[tox]
envlist = py27,py35,py36,py37

[testenv]
deps = unittest2
commands = unit2 discover []

[testenv:py36]
commands =
    unit2 discover []
    sphinx-build -b doctest docs html
    sphinx-build docs html
deps =
    unittest2
    sphinx

[testenv:py27]
commands =
    unit2 discover []
    sphinx-build -b doctest docs html
    sphinx-build docs html
deps =
    unittest2
    sphinx

mock uses unittest2 to run the tests. Invoking tox starts test discovery by executing the unit2 discover commands on Python 2.7, 3.5, 3.6 and 3.7 respectively. Against Python3.6 and Python2.7 it will additionally run sphinx-mediated doctests. If building the docs fails, due to a reST error, or any of the doctests fails, it will be reported by the tox run.

The [] parentheses in the commands provide Interactive shell substitution which means you can e.g. type:

tox -- -f -s SOMEPATH

which will ultimately invoke:

unit2 discover -f -s SOMEPATH

in each of the environments. This allows you to customize test discovery in your tox runs.

nose and tox

It is easy to integrate nosetests runs with tox. For starters here is a simple tox.ini config to configure your project for running with nose:

Basic nosetests example

Assuming the following layout:

tox.ini      # see below for content
setup.py     # a classic distutils/setuptools setup.py file

and the following tox.ini content:

[testenv]
deps = nose
# ``{posargs}`` will be substituted with positional arguments from command line
commands = nosetests {posargs}

you can invoke tox in the directory where your tox.ini resides. tox will sdist-package your project create two virtualenv environments with the python2.7 and python3.6 interpreters, respectively, and will then run the specified test command.

More examples?

Also you might want to checkout General tips and tricks and Generate documentation.

Generate documentation

It’s possible to generate the projects documentation with tox itself. The advantage of this path is that now generating the documentation can be part of the CI, and whenever any validations/checks/operations fail while generating the documentation you’ll catch it within tox.

Sphinx

No need to use the cryptic make file to generate a sphinx documentation. One can use tox to ensure all right dependencies are available within a virtual environment, and even specify the python version needed to perform the build. For example if the sphinx file structure is under the doc folder the following configuration will generate the documentation under {toxworkdir}/docs_out and print out a link to the generated documentation:

[testenv:docs]
description = invoke sphinx-build to build the HTML docs
basepython = python3.7
deps = sphinx >= 1.7.5, < 2
commands = sphinx-build -d "{toxworkdir}/docs_doctree" doc "{toxworkdir}/docs_out" --color -W -bhtml {posargs}
           python -c 'import pathlib; print("documentation available under file://\{0\}".format(pathlib.Path(r"{toxworkdir}") / "docs_out" / "index.html"))'

Note here we say we also require python 3.7, allowing us to use f-strings within the sphinx conf.py. Now one can specify a separate test environment that will validate that the links are correct.

mkdocs

Define one environment to write/generate the documentation, and another to deploy it. Use the config substitution logic to avoid defining dependencies multiple time:

[testenv:docs]
description = Run a development server for working on documentation
basepython = python3.7
deps = mkdocs >= 1.7.5, < 2
       mkdocs-material
commands = mkdocs build --clean
           python -c 'print("###### Starting local server. Press Control+C to stop server ######")'
           mkdocs serve -a localhost:8080

[testenv:docs-deploy]
description = built fresh docs and deploy them
deps = {[testenv:docs]deps}
basepython = {[testenv:docs]basepython}
commands = mkdocs gh-deploy --clean

General tips and tricks

Interactively passing positional arguments

If you invoke tox like this:

tox -- -x tests/test_something.py

the arguments after the -- will be substituted everywhere where you specify {posargs} in your test commands, for example using pytest:

[testenv]
# Could also be in a specific ``[testenv:<NAME>]`` section
commands = pytest {posargs}

or using nosetests:

[testenv]
commands = nosetests {posargs}

the above tox invocation will trigger the test runners to stop after the first failure and to only run a particular test file.

You can specify defaults for the positional arguments using this syntax:

[testenv]
commands = nosetests {posargs:--with-coverage}

Dependency changes and tracking

Creating virtual environments and installing dependencies is an expensive operation. Therefore tox tries to avoid it whenever possible, meaning it will never perform this unless it detects with absolute certainty that it needs to perform an update. A tox environment creation is made up of:

• create the virtual environment

• install dependencies specified inside deps

• if it’s a library project (has build package phase), install library dependencies (with potential extras)

These three steps are only performed once (given they all succeeded). Subsequent calls that don’t detect changes to the traits of that step will not alter the virtual environment in any way. When a change is detected for any of the steps, the entire virtual environment is removed and the operation starts from scratch (this is because it’s very hard to determine what would the delta changes would be needed - e.g. a dependency could migrate from one dependency to another, and in this case we would need to install the new while removing the old one).

Here’s what traits we track at the moment for each steps:

• virtual environment trait is tied to the python path the basepython resolves too (if this config changes, the virtual environment will be recreated),

• deps sections changes (meaning any string-level change for the entries, note requirement file content changes are not tracked),

• library dependencies are tracked at extras level (because there’s no Python API to enquire about the actual dependencies in a non-tool specific way, e.g. setuptools has one way, flit something else, and poetry another).

Whenever you change traits that are not tracked we recommend you to manually trigger a rebuild of the tox environment by passing the -r flag for the tox invocation. For instance, for a setuptools project whenever you modify the install_requires keyword at the next run force the recreation of the tox environment by passing the recreate cli tox flag.

Selecting one or more environments to run tests against

Using the -e ENV[,ENV36,...] option you explicitly list the environments where you want to run tests against. For example, given the previous sphinx example you may call:

tox -e docs

which will make tox only manage the docs environment and call its test commands. You may specify more than one environment like this:

tox -e py27,py36

which would run the commands of the py27 and py36 testenvironments respectively. The special value ALL selects all environments.

You can also specify an environment list in your tox.ini:

[tox]
envlist = py27,py36

or override it from the command line or from the environment variable TOXENV:

export TOXENV=py27,py36 # in bash style shells

Access package artifacts between multiple tox-runs

If you have multiple projects using tox you can make use of a distshare directory where tox will copy in sdist-packages so that another tox run can find the “latest” dependency. This feature allows you to test a package against an unreleased development version or even an uncommitted version on your own machine.

By default, {homedir}/.tox/distshare will be used for copying in and copying out artifacts (i.e. Python packages).

For project two to depend on the one package you use the following entry:

# example two/tox.ini
[testenv]
# install latest package from "one" project
deps = {distshare}/one-*.zip

That’s all. tox running on project one will copy the sdist-package into the distshare directory after which a tox run on project two will grab it because deps contain an entry with the one-*.zip pattern. If there is more than one matching package the highest version will be taken. tox uses verlib to compare version strings which must be compliant with PEP 386.

If you want to use this with Jenkins, also checkout the Access package artifacts between Jenkins jobs.

basepython defaults, overriding

For any pyXY test environment name the underlying pythonX.Y executable will be searched in your system PATH. Similarly, for jython and pypy the respective jython and pypy-c names will be looked for. The executable must exist in order to successfully create virtualenv environments. On Windows a pythonX.Y named executable will be searched in typical default locations using the C:\PythonXY\python.exe pattern.

All other targets will use the system python instead. You can override any of the default settings by defining the basepython variable in a specific test environment section, for example:

[testenv:docs]
basepython = python2.7

Avoiding expensive sdist

Some projects are large enough that running an sdist, followed by an install every time can be prohibitively costly. To solve this, there are two different options you can add to the tox section. First, you can simply ask tox to please not make an sdist:

[tox]
skipsdist=True

If you do this, your local software package will not be installed into the virtualenv. You should probably be okay with that, or take steps to deal with it in your commands section:

[testenv]
commands = python setup.py develop
           pytest

Running setup.py develop is a common enough model that it has its own option:

[testenv]
usedevelop=True

And a corresponding command line option --develop, which will set skipsdist to True and then perform the setup.py develop step at the place where tox normally performs the installation of the sdist. Specifically, it actually runs pip install -e . behind the scenes, which itself calls setup.py develop.

There is an optimization coded in to not bother re-running the command if $projectname.egg-info is newer than setup.py or setup.cfg.

Understanding InvocationError exit codes

When a command (defined by commands = in tox.ini) fails, it has a non-zero exit code, and an InvocationError exception is raised by tox:

ERROR: InvocationError for command
       '<command defined in tox.ini>' (exited with code 1)

If the command starts with pytest or python setup.py test for instance, then the pytest exit codes are relevant.

On unix systems, there are some rather common exit codes. This is why for exit codes larger than 128, if a signal with number equal to <exit code> - 128 is found in the signal module, an additional hint is given:

ERROR: InvocationError for command
       '<command>' (exited with code 139)
Note: this might indicate a fatal error signal (139 - 128 = 11: SIGSEGV)

where <command> is the command defined in tox.ini, with quotes removed.

The signal numbers (e.g. 11 for a segmentation fault) can be found in the “Standard signals” section of the signal man page. Their meaning is described in POSIX signals.

Beware that programs may issue custom exit codes with any value, so their documentation should be consulted.

Sometimes, no exit code is given at all. An example may be found in pytest-qt issue #170, where Qt was calling abort() instead of exit().

See also

Ignoring a command exit code.

Using tox with the Jenkins Integration Server

Using Jenkins multi-configuration jobs

The Jenkins continuous integration server allows you to define “jobs” with “build steps” which can be test invocations. If you install tox on your default Python installation on each Jenkins agent, you can easily create a Jenkins multi-configuration job that will drive your tox runs from the CI-server side, using these steps:

• install the Python plugin for Jenkins under “manage jenkins”

• create a “multi-configuration” job, give it a name of your choice

• configure your repository so that Jenkins can pull it

• (optional) configure multiple nodes so that tox-runs are performed on multiple hosts

• configure axes by using TOXENV as an axis name and as values provide space-separated test environment names you want Jenkins/tox to execute.

• add a Python-build step with this content (see also next example):

  import tox
  
  os.chdir(os.getenv("WORKSPACE"))
  tox.cmdline()  # environment is selected by ``TOXENV`` env variable
  

• check Publish JUnit test result report and enter **/junit-*.xml as the pattern so that Jenkins collects test results in the JUnit XML format.

The last point requires that your test command creates JunitXML files, for example with pytest it is done like this:

[testenv]
commands = pytest --junitxml=junit-{envname}.xml

zero-installation for agents

Note

This feature is broken currently because “toxbootstrap.py” has been removed. Please file an issue if you’d like to see it back.

If you manage many Jenkins agents and want to use the latest officially released tox (or latest development version) and want to skip manually installing tox then substitute the above Python build step code with this:

import urllib, os

url = "https://bitbucket.org/hpk42/tox/raw/default/toxbootstrap.py"
# os.environ['USETOXDEV']="1"  # use tox dev version
d = dict(__file__="toxbootstrap.py")
exec urllib.urlopen(url).read() in d
d["cmdline"](["--recreate"])

The downloaded toxbootstrap.py file downloads all necessary files to install tox in a virtual sub environment. Notes:

• uncomment the line containing USETOXDEV to use the latest development-release version of tox instead of the latest released version.

• adapt the options in the last line as needed (the example code will cause tox to reinstall all virtual environments all the time which is often what one wants in CI server contexts)

Integrating “sphinx” documentation checks in a Jenkins job

If you are using a multi-configuration Jenkins job which collects JUnit Test results you will run into problems using the previous method of running the sphinx-build command because it will not generate JUnit results. To accommodate this issue one solution is to have pytest wrap the sphinx-checks and create a JUnit result file which wraps the result of calling sphinx-build. Here is an example:

1. create a docs environment in your tox.ini file like this:

[testenv:docs]
basepython = python
# change to ``doc`` dir if that is where your sphinx-docs live
changedir = doc
deps = sphinx
       pytest
commands = pytest --tb=line -v --junitxml=junit-{envname}.xml check_sphinx.py

2. create a doc/check_sphinx.py file like this:

import subprocess


def test_linkcheck(tmpdir):
    doctrees = tmpdir.join("doctrees")
    htmldir = tmpdir.join("html")
    subprocess.check_call(
        ["sphinx-build", "-W", "-blinkcheck", "-d", str(doctrees), ".", str(htmldir)]
    )


def test_build_docs(tmpdir):
    doctrees = tmpdir.join("doctrees")
    htmldir = tmpdir.join("html")
    subprocess.check_call(
        ["sphinx-build", "-W", "-bhtml", "-d", str(doctrees), ".", str(htmldir)]
    )

3. run tox -e docs and then you may integrate this environment along with your other environments into Jenkins.

Note that pytest is only installed into the docs environment and does not need to be in use or installed with any other environment.

Access package artifacts between Jenkins jobs

In an extension to Access package artifacts between multiple tox-runs you can also configure Jenkins jobs to access each others artifacts. tox uses the distshare directory to access artifacts and in a Jenkins context (detected via existence of the environment variable HUDSON_URL); it defaults to to {toxworkdir}/distshare.

This means that each workspace will have its own distshare directory and we need to configure Jenkins to perform artifact copying. The recommend way to do this is to install the Jenkins Copy Artifact plugin and for each job which “receives” artifacts you add a Copy artifacts from another project build step using roughly this configuration:

Project-name: name of the other (tox-managed) job you want the artifact from
Artifacts to copy: .tox/dist/*.zip   # where tox jobs create artifacts
Target directory: .tox/distshare     # where we want it to appear for us
Flatten Directories: CHECK           # create no subdir-structure

You also need to configure the “other” job to archive artifacts; This is done by checking Archive the artifacts and entering:

Files to archive: .tox/dist/*.zip

So our “other” job will create an sdist-package artifact and the “copy-artifacts” plugin will copy it to our distshare area. Now everything proceeds as Access package artifacts between multiple tox-runs shows it.

So if you are using defaults you can re-use and debug exactly the same tox.ini file and make use of automatic sharing of your artifacts between runs or Jenkins jobs.

Avoiding the “path too long” error with long shebang lines

When using tox on a Jenkins instance, there may be a scenario where tox can not invoke pip because the shebang (Unix) line is too long. Some systems only support a limited amount of characters for an interpreter directive (e.x. Linux as a limit of 128). There are two methods to workaround this issue:

1. Invoke tox with the --workdir option which tells tox to use a specific directory for its virtual environments. Using a unique and short path can prevent this issue.

2. Use the environment variable TOX_LIMITED_SHEBANG to deal with environments with interpreter directive limitations (consult Handle interpreter directives with long lengths for more information).

Running tox environments in parallel

Jenkins has parallel stages allowing you to run commands in parallel, however tox package building it is not parallel safe. Use the --parallel--safe-build flag to enable parallel safe builds (this will generate unique folder names for distdir, distshare and log. Here’s a generic stage definition demonstrating how to use this inside Jenkins:

stage('run tox envs') {
  steps {
    script {
      def envs = sh(returnStdout: true, script: "tox -l").trim().split('\n')
      def cmds = envs.collectEntries({ tox_env ->
        [tox_env, {
          sh "tox --parallel--safe-build -vve $tox_env"
        }]
      })
      parallel(cmds)
    }
  }
}

Development environment

tox can be used for just preparing different virtual environments required by a project.

This feature can be used by deployment tools when preparing deployed project environments. It can also be used for setting up normalized project development environments and thus help reduce the risk of different team members using mismatched development environments.

Creating development environments using the --devenv option

The easiest way to set up a development environment is to use the --devenv option along with your existing configured testenvs. The --devenv option accepts a single argument, the location you want to create a development environment at.

For example, if I wanted to replicate the py36 environment, I could run:

$ tox --devenv venv-py36 -e py36
...
$ source venv-py36/bin/activate
(venv-py36) $ python --version
Python 3.6.7

The --devenv option skips the commands= section of that configured test environment and always sets usedevelop=true for the environment that is created.

If you don’t specify an environment with -e, the devenv feature will default to -e py – usually taking the interpreter you’re running tox with and the default [testenv] configuration.

It is possible to use the --devenv option without a tox configuration file, however the configuration file is respected if present.

Creating development environments using configuration

Here are some examples illustrating how to set up a project’s development environment using tox. For illustration purposes, let us call the development environment dev.

Example 1: Basic scenario

Step 1 - Configure the development environment

First, we prepare the tox configuration for our development environment by defining a [testenv:dev] section in the project’s tox.ini configuration file:

[testenv:dev]
basepython = python2.7
usedevelop = True

In it we state:

• what Python executable to use in the environment,

• that our project should be installed into the environment using setup.py develop, as opposed to building and installing its source distribution using setup.py install.

The development environment will reside in toxworkdir (default is .tox) just like the other tox environments.

We can configure a lot more, if we want to. For example, we can add the following to our configuration, telling tox not to reuse commands or deps settings from the base [testenv] configuration:

[testenv:dev]
commands =
deps =

Step 2 - Create the development environment

Once the [testenv:dev] configuration section has been defined, we create the actual development environment by running the following:

tox -e dev

This creates the environment at the path specified by the environment’s envdir configuration value.

Example 2: A more complex scenario

Let us say we want our project development environment to:

• use Python executable python2.7,

• pull packages from requirements.txt, located in the same directory as tox.ini.

Here is an example configuration for the described scenario:

[testenv:dev]
basepython = python2.7
usedevelop = True
deps = -rrequirements.txt

Platform specification

Basic multi-platform example

Assuming the following layout:

tox.ini      # see below for content
setup.py     # a classic distutils/setuptools setup.py file

and the following tox.ini content:

[tox]
# platform specification support is available since version 2.0
minversion = 2.0
envlist = py{27,36}-{mylinux,mymacos,mywindows}

[testenv]
# environment will be skipped if regular expression does not match against the sys.platform string
platform = mylinux: linux
           mymacos: darwin
           mywindows: win32

# you can specify dependencies and their versions based on platform filtered environments
deps = mylinux,mymacos: py==1.4.32
       mywindows: py==1.4.30

# upon tox invocation you will be greeted according to your platform
commands=
   mylinux: python -c 'print("Hello, Linus!")'
   mymacos: python -c 'print("Hello, Steve!")'
   mywindows: python -c 'print("Hello, Bill!")'

you can invoke tox in the directory where your tox.ini resides. tox creates two virtualenv environments with the python2.7 and python3.6 interpreters, respectively, and will then run the specified command according to platform you invoke tox at.

tox configuration specification

Configuration discovery

At the moment tox supports three configuration locations prioritized in the following order:

1. pyproject.toml,

2. tox.ini,

3. setup.cfg.

As far as the configuration format at the moment we only support standard ConfigParser “ini-style” format (there is a plan to add a pure TOML one soon). tox.ini and setup.cfg are such files. Note that setup.cfg requires the content to be under the tox:tox and testenv sections and is otherwise ignored. pyproject.toml on the other hand is in TOML format. However, one can inline the ini-style format under the tool.tox.legacy_tox_ini key as a multi-line string.

Below you find the specification for the ini-style format, but you might want to skim some tox configuration and usage examples first and use this page as a reference.

tox global settings

Global settings are defined under the tox section as:

[tox]
minversion = 3.4.0

minversion

Define the minimal tox version required to run; if the host’s tox version is less than this the tool will create an environment and provision it with a version of tox that satisfies this under provision_tox_env.

Changed in version 3.23.0.

When tox is invoked with the --no-provision flag, the provision won’t be attempted, tox will fail instead.

requires(LIST of PEP-508)

New in version 3.2.0.

Specify python packages that need to exist alongside the tox installation for the tox build to be able to start (must be PEP-508 compliant). Use this to specify plugin requirements (or the version of virtualenv - determines the default pip, setuptools, and wheel versions the tox environments start with). If these dependencies are not specified tox will create provision_tox_env environment so that they are satisfied and delegate all calls to that.

[tox]
requires = tox-pipenv
           setuptools >= 30.0.0

Changed in version 3.23.0.

When tox is invoked with the --no-provision flag, the provision won’t be attempted, tox will fail instead.

provision_tox_env=.tox(string)

New in version 3.8.0.

Name of the virtual environment used to provision a tox having all dependencies specified inside requires and minversion.

Changed in version 3.23.0.

When tox is invoked with the --no-provision flag, the provision won’t be attempted, tox will fail instead.

toxworkdir={toxinidir}/.tox(PATH)

Directory for tox to generate its environments into, will be created if it does not exist.

temp_dir={toxworkdir}/.tmp(PATH)

Directory where to put tox temporary files. For example: we create a hard link (if possible, otherwise new copy) in this directory for the project package. This ensures tox works correctly when having parallel runs (as each session will have its own copy of the project package - e.g. the source distribution).

skipsdist=false(true|false)

Flag indicating to perform the packaging operation or not. Set it to true when using tox for an application, instead of a library.

setupdir={toxinidir}(PATH)

Indicates where the packaging root file exists (historically the setup.py for setuptools). This will be the working directory when performing the packaging.

distdir={toxworkdir}/dist(PATH)

Directory where the packaged source distribution should be put. Note this is cleaned at the start of every packaging invocation.

sdistsrc={toxworkdir}/dist(PATH)

Do not build the package, but instead use the latest package available under this path. You can override it via the command line flag --installpkg.

distshare={homedir}/.tox/distshare(PATH)

Folder where the packaged source distribution will be moved, this is not cleaned between packaging invocations. On Jenkins (exists JENKINS_URL or HUDSON_URL environment variable) the default path is {toxworkdir}/distshare.

envlist(comma separated values)

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

New in version 3.4.0: Which tox environments are run during the tox invocation can be further filtered via the operating system environment variable TOX_SKIP_ENV regular expression (e.g. py27.* means don’t evaluate environments that start with the key py27). Skipped environments will be logged at level two verbosity level.

skip_missing_interpreters=config(config|true|false)

New in version 1.7.2.

Setting this to true will force tox to return success even if some of the specified environments were missing. This is useful for some CI systems or when 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 invocation. Setting it to config means that the value is read from the config file.

ignore_basepython_conflict=false(true|false)

New in version 3.1.0.

tox allows setting the python version for an environment via the basepython setting. If that’s not set tox can set a default value from the environment name ( e.g. py37 implies Python 3.7). Matching up the python version with the environment name has became expected at this point, leading to surprises when some configs don’t do so. To help with sanity of users a warning will be emitted whenever the environment name version does not matches up with this expectation. In a future version of tox, this warning will become an error.

Furthermore, we allow hard enforcing this rule (and bypassing the warning) by setting this flag to true. In such cases we ignore the basepython and instead always use the base python implied from the Python name. This allows you to configure basepython in the global testenv without affecting environments that have implied base python versions.

isolated_build=false(true|false)

New in version 3.3.0.

Activate isolated build environment. tox will use a virtual environment to build a source distribution from the source tree. For build tools and arguments use the pyproject.toml file as specified in PEP-517 and PEP-518. To specify the virtual environment Python version define use the isolated_build_env config section.

isolated_build_env=.package(string)

New in version 3.3.0.

Name of the virtual environment used to create a source distribution from the source tree.

Jenkins override

It is possible to override global settings inside a Jenkins instance (detection is done by checking for existence of the JENKINS_URL environment variable) by using the tox:jenkins section:

[tox:jenkins]
commands = ...  # override settings for the jenkins context

tox environments

Test environments are defined under the testenv section and individual testenv:NAME sections, where NAME is the name of a specific environment.

[testenv]
commands = ...

[testenv:NAME]
commands = ...

Settings defined in the top-level testenv section are automatically inherited by individual environments unless overridden. Test environment names can consist of alphanumeric characters and dashes; for example: py38-django30. The name will be split on dashes into multiple factors, meaning py38-django30 will be split into two factors: py38 and django30. tox defines a number of default factors, which correspond to various versions and implementations of Python and provide default values for basepython:

• pyNM: configures basepython = pythonN.M

• pyN: configures basepython = pythonN

• py: configures basepython = python

• pypyN: configures basepython = pypyN

• pypy: configures basepython = pypy

• jythonN: configures basepython = jythonN

• jython: configures basepython = jython

It is also possible to define what’s know as generative names, where an individual section maps to multiple environments. For example, py{37,38}-django{30,31} would generate four environments, each consisting of two factors: py37-django30 (py37, django30), py37-django31 (py37, django31), py38-django30 (py38, django30), and py38-django31 (py38, django31). Combined, these features provide the ability to write very concise tox.ini files. This is discussed further in below.

tox environment settings

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, this determines in practice the python for what we’ll create a virtual isolated environment. Use this to specify the python version for a tox environment. If not specified, the virtual environments factors (e.g. name part) will be used to automatically set one. For example, py37 means python3.7, py3 means python3 and py means python. provision_tox_env environment does not inherit this setting from the toxenv section.

Changed in version 3.1: After resolving this value if the interpreter reports back a different version number than implied from the name a warning will be printed by default. However, if ignore_basepython_conflict is set, the value is ignored and we force the basepython implied from the factor name.

commands(ARGVLIST)

The commands to be called for testing. Only execute if commands_pre succeed.

Each line is interpreted as one command; however a command can be split over multiple lines by ending the line with the \ character.

Commands will execute one by one in sequential fashion until one of them fails (their exit code is non-zero) or all of them succeed. The exit code of a command may be ignored (meaning they are always considered successful) by prefixing the command with a dash (-) - this is similar to how make recipe lines work. The outcome of the environment is considered successful only if all commands (these + setup + teardown) succeeded (exit code ignored via the - or success exit code value of zero).

Note

the virtual environment binary path (the bin folder within) is prepended to the os PATH, meaning commands will first try to resolve to an executable from within the virtual environment, and only after that outside of it. Therefore python translates as the virtual environments python (having the same runtime version as the basepython), and pip translates as the virtual environments pip.

Note

Inline scripts can be used, however note these are discovered from the project root directory, and is not influenced by changedir (this only affects the runtime current working directory). To make this behaviour explicit we recommend that you make inline scripts absolute paths by prepending {toxinidir}, instead of path/to/my_script prefer {toxinidir}{/}path{/}to{/}my_script. If your inline script is platform dependent refer to Platform specification on how to select different script per platform.

commands_pre(ARGVLIST)

New in version 3.4.

Commands to run before running the commands. All evaluation and configuration logic applies from commands.

commands_post(ARGVLIST)

New in version 3.4.

Commands to run after running the commands. Execute regardless of the outcome of both commands and commands_pre. All evaluation and configuration logic applies from commands.

install_command=python -m pip install {opts} {packages}(ARGV)

New in version 1.6.

Determines the command used for installing packages into the virtual environment; both the package under test and its dependencies (defined with deps). Must contain the substitution key {packages} which will be replaced by the package(s) to install. You should also accept {opts} if you are using pip – it will contain index server options such as --pre (configured as pip_pre) and potentially index-options from the deprecated indexserver option.

Note

You can also provide arbitrary commands to the install_command. Please take care that these commands can be executed on the supported operating systems. When executing shell scripts we recommend to not specify the script directly but instead pass it to the appropriate shell as argument (e.g. prefer bash script.sh over script.sh).

list_dependencies_command=python -m pip freeze(ARGV)

New in version 2.4.

The list_dependencies_command setting is used for listing the packages installed into the virtual environment.

ignore_errors=false(true|false)

New in version 2.0.

If false, a non-zero exit code from one command will abort execution of commands for that environment. If true, a non-zero exit code from one command will be ignored and further commands will be executed. The overall status will be “commands failed”, i.e. tox will exit non-zero in case any command failed.

It may be helpful to note that this setting is analogous to the -k or --keep-going option of GNU Make.

Note that in tox 2.0, the default behavior of tox with respect to treating errors from commands changed. tox < 2.0 would ignore errors by default. tox >= 2.0 will abort on an error by default, which is safer and more typical of CI and command execution tools, as it doesn’t make sense to run tests if installing some prerequisite failed and it doesn’t make sense to try to deploy if tests failed.

pip_pre=false(true|false)

New in version 1.9.

If true, adds --pre to the opts passed to install_command. If install_command uses pip, this will cause it to install the latest available pre-release of any dependencies without a specified version. If false, pip will only install final releases of unpinned dependencies.

Passing the --pre command-line option to tox will force this to true for all testenvs.

Don’t set this option if your install_command does not use pip.

allowlist_externals(MULTI-LINE-LIST)

New in version 3.18.

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 allowlist_externals=make or allowlist_externals=/usr/bin/make if you want more precision. If you don’t want tox to issue a warning in any case, just use allowlist_externals=* which will match all commands (not recommended).

Note

whitelist_externals has the same meaning and usage as allowlist_externals but it is now deprecated.

changedir={toxinidir}(PATH)

Change the current working directory when executing the test command.

Note

If the directory does not exist yet, it will be created.

deps(MULTI-LINE-LIST)

Environment dependencies - installed into the environment (see install_command) prior to project after environment creation. One dependency (a file, a URL or a package name) per line. Must be PEP-508 compliant. All installer commands are executed using the toxinidir as the current working directory.

[testenv]
deps =
    pytest
    pytest-cov >= 3.5
    pywin32 >=1.0 ; sys_platform == 'win32'
    octomachinery==0.0.13  # pyup: < 0.1.0 # disable feature updates

Changed in version 2.3.

Support for index servers is now deprecated, and its usage discouraged.

Changed in version 3.9.

Comment support on the same line as the dependency. When feeding the content to the install tool we’ll strip off content (including) from the first comment marker (#) preceded by one or more space. For example, if a dependency is octomachinery==0.0.13  # pyup: < 0.1.0 # disable feature updates it will be turned into just octomachinery==0.0.13.

platform(REGEX)

New in version 2.0.

A testenv can define a new platform setting as a regular expression. If a non-empty expression is defined and does not match against the sys.platform string the entire test environment will be skipped and none of the commands will be executed. Running tox -e <platform_name> will run commands for a particular platform and skip the rest.

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.

Notice that when updating a path variable, you can consider the use of variable substitution for the current value and to handle path separator.

[testenv]
setenv   =
    PYTHONPATH = {env:PYTHONPATH}{:}{toxinidir}

New in version 3.20.

Support for comments. Lines starting with # are ignored.

Support for environment files. Lines starting with the file| contain path to a environment file to load. Rules within the environment file are the same as within the setenv (same replacement and comment support).

passenv(SPACE-SEPARATED-GLOBNAMES)

New in version 2.0.

A list of wildcard environment variable names which shall be copied from the tox invocation environment to the test environment when executing test commands. If a specified environment variable doesn’t exist in the tox invocation environment it is ignored. You can use * and ? to match multiple environment variables with one name. The list of environment variable names is not case sensitive, and all variables that match when upper cased will be passed. For example, passing A will pass both A and a.

Some variables are always passed through to ensure the basic functionality of standard library functions or tooling like pip:

• passed through on all platforms: CURL_CA_BUNDLE, PATH, LANG, LANGUAGE, LD_LIBRARY_PATH, PIP_INDEX_URL, PIP_EXTRA_INDEX_URL, REQUESTS_CA_BUNDLE, SSL_CERT_FILE, HTTP_PROXY, HTTPS_PROXY, NO_PROXY

• Windows: SYSTEMDRIVE, SYSTEMROOT, PATHEXT, TEMP, TMP

  NUMBER_OF_PROCESSORS, USERPROFILE, MSYSTEM

• Others (e.g. UNIX, macOS): TMPDIR

You can override these variables with the setenv option.

If defined the TOX_TESTENV_PASSENV environment variable (in the tox invocation environment) can define additional space-separated variable names that are to be passed down to the test command environment.

Changed in version 2.7: PYTHONPATH will be passed down if explicitly defined. If PYTHONPATH exists in the host environment but is not declared in passenv a warning will be emitted.

recreate=false(true|false)

Always recreate virtual environment if this option is true. If this option is false, tox’s resolution mechanism will be used to determine whether to recreate the environment.

downloadcache(PATH)

IGNORED – Since pip-8 has caching by default this option is now ignored. Please remove it from your configs as a future tox version might bark on it.

sitepackages=false(true|false)

Set to true if you want to create virtual environments that also have access to globally installed packages.

Warning

In cases where a command line tool is also installed globally you have to make sure that you use the tool installed in the virtualenv by using python -m <command line tool> (if supported by the tool) or {envbindir}/<command line tool>.

If you forget to do that you will get a warning like this:

WARNING: test command found but not installed in testenv
    cmd: /path/to/parent/interpreter/bin/<some command>
    env: /foo/bar/.tox/python
Maybe you forgot to specify a dependency? See also the allowlist_externals envconfig setting.

alwayscopy=false(true|false)

Set to true if you want virtualenv to always copy files rather than symlinking.

This is useful for situations where hardlinks don’t work (e.g. running in VMS with Windows guests).

download=false(true|false)

New in version 3.10.

Set to true if you want virtualenv to upgrade pip/wheel/setuptools to the latest version. If (and only if) you want to choose a specific version (not necessarily the latest) then you can add e.g. VIRTUALENV_PIP=20.3.3 to your setenv.

args_are_paths=true(true|false)

Treat positional arguments passed to tox as file system paths and - if they exist on the filesystem - rewrite them according to the changedir. Default is true due to the exists-on-filesystem check it’s usually safe to try rewriting.

envtmpdir={envdir}/tmp(PATH)

Defines a temporary directory for the virtualenv which will be cleared each time before the group of test commands is invoked.

envlogdir={envdir}/log(PATH)

Defines a directory for logging where tox will put logs of tool invocation.

indexserver(URL)

New in version 0.9.

(DEPRECATED, will be removed in a future version) Use setenv to configure PIP_INDEX_URL environment variable, see below.

Multi-line name = URL definitions of python package servers. You can specify an alternative index server for dependencies by applying the :indexservername:depname pattern. The default indexserver definition determines where unscoped dependencies and the sdist install installs from. Example:

[tox]
indexserver =
    default = https://mypypi.org

will make tox install all dependencies from this PyPI index server (including when installing the project sdist package).

The recommended way to set a custom index server URL is to use setenv:

[testenv]
setenv =
    PIP_INDEX_URL = {env:PIP_INDEX_URL:https://pypi.org/simple/}

This will ensure the desired index server gets used for virtual environment creation and allow overriding the index server URL with an environment variable.

envdir={toxworkdir}/{envname}(PATH)

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

usedevelop=false(true|false)

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

skip_install=false(true|false)

New in version 1.9.

Do not install the current package. This can be used when you need the virtualenv management but do not want to install the current package into that environment.

ignore_outcome=false(true|false)

New in version 2.2.

If set to true a failing result of this testenv will not make tox fail, only a warning will be produced.

extras(MULTI-LINE-LIST)

New in version 2.4.

A list of “extras” to be installed with the sdist or develop install. For example, extras = testing is equivalent to [testing] in a pip install command. These are not installed if skip_install is true.

description=no description(SINGLE-LINE-TEXT)

A short description of the environment, this will be used to explain the environment to the user upon listing environments for the command line with any level of verbosity higher than zero.

parallel_show_output=false(bool)

New in version 3.7.0.

If set to True the content of the output will always be shown when running in parallel mode.

depends(comma separated values)

New in version 3.7.0.

tox environments this depends on. tox will try to run all dependent environments before running this environment. Format is same as envlist (allows factor usage).

Warning

depends does not pull in dependencies into the run target, for example if you select py27,py36,coverage via the -e tox will only run those three (even if coverage may specify as depends other targets too - such as py27, py35, py36, py37).

suicide_timeout=0.0(float)

New in version 3.15.2.

When an interrupt is sent via Ctrl+C or the tox process is killed with a SIGTERM, a SIGINT is sent to all foreground processes. The suicide_timeout gives the running process time to cleanup and exit before receiving (in some cases, a duplicate) SIGINT from tox.

interrupt_timeout=0.3(float)

New in version 3.15.0.

When tox is interrupted, it propagates the signal to the child process after suicide_timeout seconds. If the process still hasn’t exited after interrupt_timeout seconds, its sends a SIGTERM.

terminate_timeout=0.2(float)

New in version 3.15.0.

When tox is interrupted, after waiting interrupt_timeout seconds, it propagates the signal to the child process, waits interrupt_timeout seconds, sends it a SIGTERM, waits terminate_timeout seconds, and sends it a SIGKILL if it hasn’t exited.

Substitutions

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

You can escape curly braces with the \ character if you need them, for example:

commands = echo "\{posargs\}" = {posargs}

Note some substitutions (e.g. posargs, env) may have addition values attached to it, via the : character (e.g. posargs - default value, env - key). Such substitutions cannot have a space after the : character (e.g. {posargs: magic} while being at the start of a line inside the ini configuration (this would be parsed as factorial {posargs, having value magic).

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}

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

{:}

OS-specific path separator (: on *nix family, ; on Windows). May be used in setenv, when target variable is path variable (e.g. PATH or PYTHONPATH).

{/}

OS-specific directory separator (/ on *nix family, \\ on Windows). Useful for deriving filenames from preset paths, as arguments for commands that requires \\ on Windows. e.g. {distdir}{/}file.txt. It is not usually needed when using commands written in Python.

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

Substitutions can also be nested. In that case they are expanded starting from the innermost expression:

{env:KEY:{env:DEFAULT_OF_KEY}}

the above example is roughly equivalent to os.environ.get('KEY', os.environ['DEFAULT_OF_KEY'])

Interactive shell substitution

It’s possible to inject a config value only when tox is running in interactive shell (standard input):

{tty:ON_VALUE:OFF_VALUE}

The first value is the value to inject when the interactive terminal is available, the second value is the value to use when it’s not. The later on is optional. A good use case for this is e.g. passing in the --pdb flag for pytest.

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 referred 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 repeating the same values:

[base]
deps =
    pytest
    mock
    pytest-xdist

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

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

Generating environments, conditional settings

New in version 1.8.

Suppose you want to test your package against python2.7, python3.6 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 = {py27,py36}-django{15,16}

[testenv]
deps =
    pytest
    django15: Django>=1.5,<1.6
    django16: Django>=1.6,<1.7
    py36: unittest2
commands = pytest

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 = {py36,py27}-django{15,16}

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

py27-django15
py27-django16
py36-django15
py36-django16

You can still list environments explicitly along with generated ones:

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

Keep in mind that whitespace characters (except newline) within {} are stripped, so the following line defines the same environment names:

envlist = {py27,py36}-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
py27-django15
py27-django16
py36-django15
py36-django16
docs
flake

Generative section names

New in version 3.15.

Using similar syntax, it is possible to generate sections:

[testenv:py{27,36}-flake]

This is equivalent to defining distinct sections:

$ tox -a
py27-flake
py36-flake

It is useful when you need an environment different from the default one, but still want to take advantage of factor-conditional settings.

Factors and factor-conditional settings

As discussed previously, parts of an environment name delimited by hyphens are called factors and can be used to set values conditionally. In list settings such as deps or commands you can freely intermix optional lines with unconditional ones:

[testenv]
deps =
    pytest
    django15: Django>=1.5,<1.6
    django16: Django>=1.6,<1.7
    py36: 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,

• unittest2 will be loaded for Python 3.6 environments.

tox provides a number of default factors corresponding to Python interpreter versions. The conditional setting above will lead to either python3.6 or python2.7 used as base python, e.g. python3.6 is selected if current environment contains py36 factor.

Note

Configuring basepython for environments using default factors will result in a warning. Configure ignore_basepython_conflict if you wish to explicitly ignore these conflicts, allowing you to define a global basepython for all environments except those with default factors.

Complex factor conditions

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

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

[testenv]
deps =
    py34-mysql: PyMySQL     # use if both py34 and mysql are in the env name
    py27,py36: urllib3      # use if either py36 or py27 are in the env name
    py{27,36}-sqlite: mock  # mocking sqlite in python 2.x & 3.6
    !py34-sqlite: mock      # mocking sqlite, except in python 3.4
    sqlite-!py34: mock      # (same as the line above)
    !py34-!py36: enum34     # use if neither py34 nor py36 are in the env name

Take a look at the first deps line. It shows how you can special case something for a combination of factors, by just hyphenating the combining factors together. This particular line states that PyMySQL will be loaded for python 3.4, mysql environments, e.g. py34-django15-mysql and py34-django16-mysql.

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

The remaining lines all have the same effect and use conditions equivalent to py27-sqlite,py36-sqlite. They have all been added only to help demonstrate the following:

• how factor expressions get expanded the same way as in envlist

• how to use negated factor conditions by prefixing negated factors with !

• that the order in which factors are hyphenated together does not matter

Note

Factors don’t do substring matching against env name, instead every hyphenated expression is split by - and if ALL of its non-negated factors and NONE of its negated ones are also factors of an env then that condition is considered to hold for that env.

For example, environment py36-mysql-!dev:

• would be matched by expressions py36, py36-mysql or mysql-py36,

• but not py2, py36-sql or py36-mysql-dev.

Factors and values substitution are compatible

It is possible to mix both values substitution and factor expressions. For example:

[tox]
envlist = py27,py36,coverage

[testenv]
deps =
    flake8
    coverage: coverage

[testenv:py27]
deps =
    {[testenv]deps}
    pytest

With the previous configuration, it will install:

• flake8 and pytest packages for py27 environment.

• flake8 package for py36 environment.

• flake8 and coverage packages for coverage environment.

Advanced settings

Handle interpreter directives with long lengths

For systems supporting executable text files (scripts with a shebang), the system will attempt to parse the interpreter directive to determine the program to execute on the target text file. When tox prepares a virtual environment in a file container which has a large length (e.x. using Jenkins Pipelines), the system might not be able to invoke shebang scripts which define interpreters beyond system limits (e.x. Linux as a limit of 128; BINPRM_BUF_SIZE). To workaround an environment which suffers from an interpreter directive limit, a user can bypass the system’s interpreter parser by defining the TOX_LIMITED_SHEBANG environment variable before invoking tox:

export TOX_LIMITED_SHEBANG=1

When the workaround is enabled, all tox-invoked text file executables will have their interpreter directive parsed by and explicitly executed by tox.

Environment variables

tox will treat the following environment variables:

• TOX_DISCOVER for python discovery first try the python executables under these paths

• TOXENV see envlist.

• TOX_LIMITED_SHEBANG see Handle interpreter directives with long lengths.

• TOX_PARALLEL_NO_SPINNER see Parallel mode.

• _TOX_PARALLEL_ENV lets tox know that it is invoked in the parallel mode.

• TOX_PROVISION is only intended to be used internally.

• TOX_REPORTER_TIMESTAMP enables showing for each output line its delta since the tox startup when set to 1.

• TOX_SKIP_ENV see envlist.

• TOX_TESTENV_PASSENV see passenv.

Injected environment variables

tox will inject the following environment variables that you can use to test that your command is running within tox:

New in version 3.4.

• TOX_WORK_DIR env var is set to the tox work directory

• TOX_ENV_NAME is set to the current running tox environment name

• TOX_ENV_DIR is set to the current tox environments working dir.

• TOX_PACKAGE the packaging phases outcome path (useful to inspect and make assertion of the built package itself).

• TOX_PARALLEL_ENV is set to the current running tox environment name, only when running in parallel mode.

note

this applies for all tox envs (isolated packaging too) and all external commands called (e.g. install command - pip).

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.

CLI

tox

tox options

usage: tox [--version] [-h] [--help-ini] [-v] [-q] [--showconfig] [-l] [-a] [-c CONFIGFILE] [-e envlist] [--devenv ENVDIR] [--notest] [--sdistonly] [--skip-pkg-install] [-p [VAL]] [-o]
           [--parallel--safe-build] [--installpkg PATH] [--develop] [-i URL] [--pre] [-r] [--result-json PATH] [--discover PATH [PATH ...]] [--hashseed SEED] [--force-dep REQ]
           [--sitepackages] [--alwayscopy] [--no-provision [REQUIRES_JSON]] [-s [val]] [--workdir PATH]
           [args [args ...]]

args

additional arguments available to command positional substitution

--version

report version information to stdout.

-h, --help

show help about options

--help-ini, --hi

show help about ini-names

-v, --verbose

increase verbosity of reporting output.-vv mode turns off output redirection for package installation, above level two verbosity flags are passed through to pip (with two less level)

-q, --quiet

progressively silence reporting output.

--showconfig

show live configuration (by default all env, with -l only default targets, specific via TOXENV/-e)

-l, --listenvs

show list of test environments (with description if verbose)

-a, --listenvs-all

show list of all defined environments (with description if verbose)

-c <configfile>

config file name or directory with ‘tox.ini’ file.

-e <envlist>

work against specified environments (ALL selects all).

--devenv <envdir>

sets up a development environment at ENVDIR based on the env’s tox configuration specified by -e (-e defaults to py).

--notest

skip invoking test commands.

--sdistonly

only perform the sdist packaging activity.

--skip-pkg-install

skip package installation for this run

-p <val>, --parallel <val>

run tox environments in parallel, the argument controls limit: all, auto or missing argument - cpu count, some positive number, 0 to turn off

-o, --parallel-live

connect to stdout while running environments

--parallel--safe-build

(deprecated) ensure two tox builds can run in parallel (uses a lock file in the tox workdir with .lock extension)

--installpkg <path>

use specified package for installation into venv, instead of creating an sdist.

--develop

install package in the venv using ‘setup.py develop’ via ‘pip -e .’

-i <url>, --index-url <url>

set indexserver url (if URL is of form name=url set the url for the ‘name’ indexserver, specifically)

--pre

install pre-releases and development versions of dependencies. This will pass the –pre option to install_command (pip by default).

-r, --recreate

force recreation of virtual environments

--result-json <path>

write a json file with detailed information about all commands and results involved.

--discover <path>

for python discovery first try the python executables under these paths

--hashseed <seed>

set PYTHONHASHSEED to SEED before running commands. Defaults to a random integer in the range [1, 4294967295] ([1, 1024] on Windows). Passing ‘noset’ suppresses this behavior.

--force-dep <req>

Forces a certain version of one of the dependencies when configuring the virtual environment. REQ Examples ‘pytest<2.7’ or ‘django>=1.6’.

--sitepackages

override sitepackages setting to True in all envs

--alwayscopy

override alwayscopy setting to True in all envs

--no-provision <requires_json>

do not perform provision, but fail and if a path was provided write provision metadata as JSON to it

-s, --skip-missing-interpreters

don’t fail tests for missing interpreters: {config,true,false} choice

--workdir <path>

tox working directory

Support and contact channels

Getting in contact:

• join the tox-dev mailing list for tox related questions and development discussions

• file a report on the issue tracker

• hang out on the tox discord server channel at https://discord.gg/tox

• fork the github repository and submit merge/pull requests (see the developers help page – Developers FAQ)

Paid professional support

Contact holger at merlinux.eu, an association of experienced well-known Python developers.

Changelog history

Versions follow Semantic Versioning (<major>.<minor>.<patch>). Backward incompatible (breaking) changes will only be introduced in major versions with advance notice in the Deprecations section of releases.

v3.24.1 (2021-07-31) Bugfixes ^^^^^^^^

• get_requires_for_build_sdist hook (PEP 517) is assumed to return an empty list if left unimplemented by the backend build system - by @oczkoisse #2130

Documentation

• The documentation of install_command now also mentions that you can provide arbitrary commands - by @jugmac00 #2081

v3.24.0 (2021-07-14)

Bugfixes

• --devenv no longer modifies the directory in which the .tox environment is provisioned - by @isaac-ped #2065

• Fix show config when the package names are not in canonical form - by @gaborbernat. #2103

Documentation

• Extended environment variables section - by @majiang #2036

Miscellaneous

• tox no longer shows deprecation warnings for distutils.sysconfig on Python 3.10 - by @9999years #2100

v3.23.1 (2021-05-05)

Bugfixes

• Distinguish between normal Windows Python and MSYS2 Python when looking for virtualenv executable path. Adds os.sep to InterpreterInfo - by @jschwartzentruber #1982

• Fix a tox-conda isolation build bug - by @AntoineD. #2056

Documentation

• Update examples in the documentation to use setenv in the [testenv] sections, not wrongly in the [tox] main section. - by @AndreyNautilus #1999

Miscellaneous

• Enable building tox with setuptools_scm 6+ by @hroncok #1984

v3.23.0 (2021-03-03)

Features

• tox can now be invoked with a new --no-provision flag that prevents provision, if requires or minversion are not satisfied, tox will fail; if a path is specified as an argument to the flag (e.g. as tox --no-provision missing.json) and provision is prevented, provision metadata are written as JSON to that path - by @hroncok #1921

• Unicode support in pyproject.toml - by @domdfcoding #1940

v3.22.0 (2021-02-16)

Features

• The value of the requires configuration option is now exposed via the tox.config.Config object - by @hroncok #1918

v3.21.4 (2021-02-02)

Bugfixes

• Adapt tests not to assume the easy_install command exists, as it was removed from setuptools 52.0.0+ - by @hroncok #1893

v3.21.3 (2021-01-28)

Bugfixes

• Fix a killed tox (via SIGTERM) leaving the commands subprocesses running by handling it as if it were a KeyboardInterrupt - by @dajose #1772

v3.21.2 (2021-01-19)

Bugfixes

• Newer coverage tools update the COV_CORE_CONTEXT environment variable, add it to the list of environment variables that can change in our pytest plugin - by @gaborbernat. #1854

v3.21.1 (2021-01-13)

Bugfixes

• Fix regression that broke using install_command in config replacements - by @jayvdb #1777

• Fix regression parsing posargs default containing colon. - by @jayvdb #1785

Features

• Prevent .tox in envlist - by @jayvdb #1684

Miscellaneous

• Enable building tox with setuptools_scm 4 and 5 by @hroncok #1799

v3.21.0 (2021-01-08)

Bugfixes

• Fix the false congratulations message that appears when a KeyboardInterrupt occurs during package installation. - by @gnikonorov #1453

• Fix platform support for install_command. - by @jayvdb #1464

• Fixed regression in v3.20.0 that caused escaped curly braces in setenv to break usage of the variable elsewhere in tox.ini. - by @jayvdb #1690

• Prevent {} and require {: is only followed by }. - by @jayvdb #1711

• Raise MissingSubstitution on access of broken ini setting. - by @jayvdb #1716

Features

• Allow { and } in default of {env:key:default}. - by @jayvdb #1502

• Allow {posargs} in setenv. - by @jayvdb #1695

• Allow {/} to refer to os.sep. - by @jayvdb #1700

• Make parsing [testenv] sections in setup.cfg official. - by @mauvilsa #1727

• Relax importlib requirement to allow 3.0.0 or any newer version - by @pkolbus #1763

Documentation

• Document more info about using platform setting. - by @prakhargurunani #1144

• Replace indexserver in documentation with environment variables - by @ziima. #1357

• Document that the passenv environment setting is case insensitive. - by @gnikonorov #1534

v3.20.1 (2020-10-09)

Bugfixes

• Relax importlib requirement to allow version<3 - by @usamasadiq #1682

v3.20.0 (2020-09-01)

Bugfixes

• Allow hyphens and empty factors in generative section name. - by @tyagdit #1636

• Support for PEP517 in-tree build backend-path key in get-build-requires. - by @nizox #1654

• Allow escaping curly braces in setenv. - by @mkenigs #1656

Features

• Support for comments within setenv and environment files via the files| prefix. - by @gaborbernat #1667

v3.19.0 (2020-08-06)

Bugfixes

• skip setup.cfg if it has no tox:tox namespace - by @hroncok #1045

Features

• Implement support for building projects having PEP 517#in-tree-build-backends backend-path setting - by @webknjaz #1575

• Don’t require a tox config file for tox --devenv - by @hroncok #1643

Documentation

• Fixed grammar in top-level documentation - by @tfurf #1631

v3.18.1 (2020-07-28)

Bugfixes

• Fix TypeError when using isolated_build with backends that are not submodules (e.g. maturin) #1629

v3.18.0 (2020-07-23)

Deprecations (removal in next major release)

• Add allowlist_externals alias to whitelist_externals (whitelist_externals is now deprecated). - by @dajose #1491

v3.17.1 (2020-07-15)

Bugfixes

• Fix tests when the HOSTNAME environment variable is set, but empty string - by @hroncok #1616

v3.17.0 (2020-07-14)

Features

• The long arguments --verbose and --quiet (rather than only their short forms, -v and -q) are now accepted. #1612

• The ResultLog now prefers HOSTNAME environment variable value (if set) over the full qualified domain name of localhost. This makes it possible to disable an undesired DNS lookup, which happened on all tox invocations, including trivial ones - by @hroncok #1615

Documentation

• Update packaging information for Flit. #1613

v3.16.1 (2020-06-29)

Bugfixes

• Fixed the support for using {temp_dir} in tox.ini - by @webknjaz #1609

v3.16.0 (2020-06-26)

Features

• Allow skipping the package and installation step when passing the --skip-pkg-install. This should be used in pair with the --notest, so you can separate environment setup and test run:

  tox -e py --notest
  tox -e py --skip-pkg-install
  

  by @gaborbernat. #1605

Miscellaneous

• Improve config parsing performance by precompiling commonly used regular expressions - by @brettlangdon #1603

v3.15.2 (2020-06-06)

Bugfixes

• Add an option to allow a process to suicide before sending the SIGTERM. - by @jhesketh #1497

• PyPy 7.3.1 on Windows uses the Script folder instead of bin. - by @gaborbernat #1597

Miscellaneous

• Allow to run the tests with pip 19.3.1 once again while preserving the ability to use pip 20.1 - by @hroncok #1594

v3.15.1 (2020-05-20)

Bugfixes

• tox --showconfig no longer tries to interpolate ‘%’ signs. #1585

v3.15.0 (2020-05-02)

Bugfixes

• Respect attempts to change PATH via setenv - by @aklajnert. #1423

• Fix parsing of architecture in python interpreter name. - by @bruchar1 #1542

• Prevent exception when command is empty. - by @bruchar1 #1544

• Fix irrelevant Error message for invalid argument when running outside a directory with tox support files by @nkpro2000sr. #1547

Features

• Allow parallel mode without arguments. - by @ssbarnea #1418

• Allow generative section name expansion. - by @bruchar1 #1545

• default to passing the env var PIP_EXTRA_INDEX_URL by @georgealton. #1561

Documentation

• Improve documentation about config by adding tox environment description at start - by @stephenfin. #1573

v3.14.6 (2020-03-25)

Bugfixes

• Exclude virtualenv dependency versions with known regressions (20.0.[0-7]) - by @webknjaz. #1537

• Fix tox -h and tox --hi shows an error when run outside a directory with tox support files by @nkpro2000sr. #1539

• Fix ValueError on tox -l for a tox.ini file that does not contain an envlist definition. - by @jquast. #1343

v3.14.5 (2020-02-16)

Features

• Add --discover (fallback to TOX_DISCOVER environment variable via path separator) to inject python executables to try as first step of a discovery - note the executable still needs to match the environment by @gaborbernat. #1526

v3.14.4 (2020-02-13)

Bugfixes

• Bump minimal six version needed to avoid using one incompatible with newer virtualenv. - by @ssbarnea #1519

• Avoid pypy test failure due to undefined printout var. - by @ssbarnea #1521

Features

• Add interrupt_timeout and terminate_timeout that configure delay between SIGINT, SIGTERM and SIGKILL when tox is interrupted. - by @sileht #1493

• Add HTTP_PROXY, HTTPS_PROXY and NO_PROXY to default passenv. - by @pfmoore #1498

v3.14.3 (2019-12-27)

Bugfixes

• Relax importlib requirement to allow either version 0 or 1 - by @chyzzqo2 #1476

Miscellaneous

• Clarify legacy setup.py error message: python projects should commit to a strong consistency of message regarding packaging. We no-longer tell people to add a setup.py to their already configured pep-517 project, otherwise it could imply that pyproject.toml isn’t as well supported and recommended as it truly is - by @graingert #1478

v3.14.2 (2019-12-02)

Bugfixes

• Fix fallback to global configuration when running in Jenkins. - by @daneah #1428

• Fix colouring on windows: colorama is a dep. - by @1138-4EB #1471

Miscellaneous

• improve performance with internal lookup of Python version information - by @blueyed #1462

• Use latest version of importlib_metadata package - by @kammala #1472

• Mark poetry related tests as xfail since its dependency pyrsistent won’t install in ci due to missing wheels/build deps. - by @RonnyPfannschmidt #1474

v3.14.1 (2019-11-13)

Bugfixes

• fix reporting of exiting due to (real) signals - by @blueyed #1401

• Bump minimal virtualenv to 16.0.0 to improve own transitive deps handling in some ancient envs. — by @webknjaz #1429

• Adds CURL_CA_BUNDLE, REQUESTS_CA_BUNDLE, SSL_CERT_FILE to the default passenv values. - by @ssbarnea #1437

• Fix nested tox execution in the parallel mode by separating the environment variable that let’s tox know it is invoked in the parallel mode (_TOX_PARALLEL_ENV) from the variable that informs the tests that tox is running in parallel mode (TOX_PARALLEL_ENV). — by @hroncok #1444

• Fix provisioning from a pyvenv interpreter. — by @kentzo #1452

Deprecations (removal in next major release)

• Python 3.4 is no longer supported. — by @gaborbernat #1456

v3.14.0 (2019-09-03)

Bugfixes

• Fix PythonSpec detection of python3.10 - by @asottile #1374

• Fix regression failing to detect future and past py## factors - by @asottile #1377

• Fix current_tox_py for pypy / pypy3 - by @asottile #1378

• Honor environment markers in requires list - by @asottile #1380

• improve recreate check by allowing directories containing .tox-config1 (the marker file created by tox) - by @asottile #1383

• Recognize correctly interpreters that have suffixes (like python3.7-dbg). #1415

Features

• Add support for minor versions with multiple digits tox -e py310 works for python3.10 - by @asottile #1374

• Remove dependence on md5 hashing algorithm - by @asottile #1384

Documentation

• clarify behaviour if recreate is set to false - by @PJCampi #1399

Miscellaneous

• Fix relative URLs to files in the repo in .github/PULL_REQUEST_TEMPLATE.md — by @webknjaz #1363

• Replace importlib_metadata backport with importlib.metadata from the standard library on Python 3.8+ - by @hroncok #1367

• Render the change fragment help on the docs/changelog/ directory view on GitHub — by @webknjaz #1370

v3.13.2 (2019-07-01)

Bugfixes

• on venv cleanup: add explicit check for pypy venv to make it possible to recreate it - by @obestwalter #1355

• non canonical names within requires cause infinite provisioning loop - by @gaborbernat #1359

v3.13.1 (2019-06-25)

Bugfixes

• Fix isolated build double-requirement - by @asottile. #1349

v3.13.0 (2019-06-24)

Bugfixes

• tox used Windows shell rules on non-Windows platforms when transforming positional arguments to a string - by @barneygale. #1336

Features

• Replace pkg_resources with importlib_metadata for speed - by @asottile. #1324

• Add the --devenv ENVDIR option for creating development environments from [testenv] configurations - by @asottile. #1326

• Refuse to delete envdir if it doesn’t look like a virtualenv - by @asottile. #1340

v3.12.1 (2019-05-23)

Bugfixes

• Ensure TOX_WORK_DIR is a native string in os.environ - by @asottile. #1313

• Fix import and usage of winreg for python2.7 on windows - by @asottile. #1315

• Fix Windows selects incorrect spec on first discovery - by @gaborbernat #1317

v3.12.0 (2019-05-23)

Bugfixes

• When using --parallel with --result-json the test results are now included the same way as with serial runs - by @fschulze #1295

• Turns out the output of the py -0p is not stable yet and varies depending on various edge cases. Instead now we read the interpreter values directly from registry via PEP-514 - by @gaborbernat. #1306

Features

• Adding TOX_PARALLEL_NO_SPINNER environment variable to disable the spinner in parallel mode for the purposes of clean output when using CI tools - by @zeroshift #1184

v3.11.1 (2019-05-16)

Bugfixes

• When creating virtual environments we no longer ask the python to tell its path, but rather use the discovered path. #1301

v3.11.0 (2019-05-15)

Features

• --showconfig overhaul:

  • now fully generated via the config parser, so anyone can load it by using the built-in python config parser

  • the tox section contains all configuration data from config

  • the tox section contains a host_python key detailing the path of the host python

  • the tox:version section contains the versions of all packages tox depends on with their version

  • passing -l now allows only listing default target envs

  • allows showing config for a given set of tox environments only via the -e cli flag or the TOXENV environment variable, in this case the tox and tox:version section is only shown if at least one verbosity flag is passed

  this should help inspecting the options. #1298

v3.10.0 (2019-05-13)

Bugfixes

• fix for tox -l command: do not allow setting the TOXENV or the -e flag to override the listed default environment variables, they still show up under extra if non defined target - by @gaborbernat #720

• tox ignores unknown CLI arguments when provisioning is on and outside of the provisioned environment (allowing provisioning arguments to be forwarded freely) - by @gaborbernat #1270

Features

• Virtual environments created now no longer upgrade pip/wheel/setuptools to the latest version. Instead the start packages after virtualenv creation now is whatever virtualenv has bundled in. This allows faster virtualenv creation and builds that are easier to reproduce. #448

• Improve python discovery and add architecture support:

  • UNIX:

    • First, check if the tox host Python matches.

    • Second, check if the the canonical name (e.g. python3.7, python3) matches or the base python is an absolute path, use that.

    • Third, check if the the canonical name without version matches (e.g. python, pypy) matches.

  • Windows:

    • First, check if the tox host Python matches.

    • Second, use the py.exe to list registered interpreters and any of those match.

    • Third, check if the the canonical name (e.g. python3.7, python3) matches or the base python is an absolute path, use that.

    • Fourth, check if the the canonical name without version matches (e.g. python, pypy) matches.

    • Finally, check for known locations (c:\python{major}{minor}\python.exe).

  tox environment configuration generation is now done in parallel (to alleviate the slowdown due to extra checks). #1290

v3.9.0 (2019-04-17)

Bugfixes

• Fix congratulations when using ^C during virtualenv creation - by @asottile #1257

Features

• Allow having inline comments in deps — by @webknjaz #1262

v3.8.6 (2019-04-03)

Bugfixes

• parallel_show_output does not work with tox 3.8 #1245

v3.8.5 (2019-04-03)

Bugfixes

• the isolated build env now ignores sitepackages, deps and description as these do not make sense - by @gaborbernat #1239

• Do not print timings with more than 3 decimal digits on Python 3 - by @mgedmin. #1241

v3.8.4 (2019-04-01)

Bugfixes

• Fix sdist creation on python2.x when there is non-ascii output. #1234

• fix typos in isolated.py that made it impossible to install package with requirements in pyproject.toml - by @unmade #1236

v3.8.3 (2019-03-29)

Bugfixes

• don’t crash when version information is not available for a proposed base python - by @gaborbernat #1227

• Do not print exception traceback when the provisioned tox fails - by @gaborbernat #1228

v3.8.2 (2019-03-29)

Bugfixes

• using -v and -e connected (as -ve) fails - by @gaborbernat #1218

• Changes to the plugin tester module (cmd no longer sets PYTHONPATH), and action.popen no longer returns the command identifier information from within the logs. No public facing changes. #1222

• Spinner fails in CI on UnicodeEncodeError - by @gaborbernat #1223

v3.8.1 (2019-03-28)

Bugfixes

• The -eALL command line argument now expands the envlist key and includes all its environment. #1155

• Isolated build environment dependency overrides were not taken in consideration (and such it inherited the deps from the testenv section) - by @gaborbernat #1207

• --result-json puts the command into setup section instead of test (pre and post commands are now also correctly put into the commands section) - by @gaborbernat #1210

• Set setup.cfg encoding to UTF-8 as it contains Unicode characters. #1212

• Fix tox CI, better error reporting when locating via the py fails - by @gaborbernat #1215

v3.8.0 (2019-03-27)

Bugfixes

• In a posix shell, setting the PATH environment variable to an empty value is equivalent to not setting it at all; therefore we no longer if the user sets PYTHONPATH an empty string on python 3.4 or later - by @gaborbernat. #1092

• Fixed bug of children process calls logs clashing (log already exists) - by @gaborbernat #1137

• Interpreter discovery and virtualenv creation process calls that failed will now print out on the screen their output (via the logfile we automatically save) - by @gaborbernat #1150

• Using py2 and py3 with a specific basepython will no longer raise a warning unless the major version conflicts - by @demosdemon. #1153

• Fix missing error for tox -e unknown when tox.ini declares envlist. - by @medmunds #1160

• Resolve symlinks with toxworkdir - by @blueyed. #1169

• Interrupting a tox call (e.g. via CTRL+C) now will ensure that spawn child processes (test calls, interpreter discovery, parallel sub-instances, provisioned hosts) are correctly stopped before exiting (via the pattern of INTERRUPT - 300 ms, TERMINATE - 200 ms, KILL signals) - by @gaborbernat #1172

• Fix a ResourceWarning: unclosed file in Action - by @BoboTiG. #1179

• Fix deadlock when using --parallel and having environments with lots of output - by @asottile. #1183

• Removed code that sometimes caused a difference in results between --parallel and -p when using posargs - by @timdaman #1192

Features

• tox now auto-provisions itself if needed (see tox auto-provisioning). Plugins or minimum version of tox no longer need to be manually satisfied by the user, increasing their ease of use. - by @gaborbernat #998

• tox will inject the TOX_PARALLEL_ENV environment variable, set to the current running tox environment name, only when running in parallel mode. - by @gaborbernat #1139

• Parallel children now save their output to a disk logfile - by @gaborbernat #1143

• Parallel children now are added to --result-json - by @gaborbernat #1159

• Display pattern and sys.platform with platform mismatch - by @blueyed. #1176

• Setting the environment variable TOX_REPORTER_TIMESTAMP to 1 will enable showing for each output line its delta since the tox startup. This can be especially handy when debugging parallel runs.- by @gaborbernat #1203

Documentation

• Add a poetry examples to packaging - by @gaborbernat #1163

v3.7.0 (2019-01-11)

Features

• Parallel mode added (alternative to detox which is being deprecated), for more details see Parallel mode - by @gaborbernat. #439

• Added command line shortcut -s for --skip-missing-interpreters - by @evandrocoan #1119

Deprecations (removal in next major release)

• Whitelisting of externals will be mandatory in tox 4: issue a deprecation warning as part of the already existing warning - by @obestwalter #1129

Documentation

• Clarify explanations in examples and avoid unsupported end line comments - by @obestwalter #1110

• Set to PULL_REQUEST_TEMPLATE.md use relative instead of absolute URLs - by @evandrocoan Fixed PULL_REQUEST_TEMPLATE.md path for changelog/examples.rst to docs/changelog/examples.rst - by @evandrocoan #1120

v3.6.1 (2018-12-24)

Features

• if the packaging phase successfully builds a package set it as environment variable under TOX_PACKAGE (useful to make assertions on the built package itself, instead of just how it ends up after installation) - by @gaborbernat (#1081)

v3.6.0 (2018-12-13)

Bugfixes

• On windows, check sys.executable before others for interpreter version lookup. This matches what happens on non-windows. (#1087)

• Don’t rewrite {posargs} substitution for absolute paths. (#1095)

• Correctly fail tox --notest when setup fails. (#1097)

Documentation

• Update Contributor Covenant URL to use https:// - by @jdufresne. (#1082)

• Correct the capitalization of PyPI throughout the documentation - by @jdufresne. (#1084)

• Link to related projects (Invoke and Nox) from the documentation - by @theacodes. (#1088)

Miscellaneous

• Include the license file in the wheel distribution - by @jdufresne. (#1083)

v3.5.3 (2018-10-28)

Bugfixes

• Fix bug with incorrectly defactorized dependencies - by @bartsanchez (#706)

• do the same transformation to egg_info folders that pkg_resources does; this makes it possible for hyphenated names to use the develop-inst-noop optimization (cf. 910), which previously only worked with non-hyphenated egg names - by @hashbrowncipher (#1051)

• previously, if a project’s setup.py --name emitted extra information to stderr, tox would capture it and consider it part of the project’s name; now, emissions to stderr are printed to the console - by @hashbrowncipher (#1052)

• change the way we acquire interpreter information to make it compatible with jython interpreter, note to create jython envs one needs virtualenv > 16.0 which will be released later @gaborbernat (#1073)

Documentation

• document substitutions with additional content starting with a space cannot be alone on a line inside the ini file - by @gaborbernat (#437)

• change the spelling of a single word from contrains to the proper word, constraints - by @metasyn (#1061)

• Mention the minimum version required for commands_pre/commands_post support. (#1071)

v3.5.2 (2018-10-09)

Bugfixes

• session packages are now put inside a numbered directory (instead of prefix numbering it, because pip fails when wheels are not named according to PEP-491, and prefix numbering messes with this) - by @gaborbernat (#1042)

Features

• level three verbosity (-vvv) show the packaging output - by @gaborbernat (#1047)

v3.5.1 (2018-10-08)

Bugfixes

• fix regression with 3.5.0: specifying --installpkg raises AttributeError: 'str' object has no attribute 'basename' (#1042)

v3.5.0 (2018-10-08)

Bugfixes

• intermittent failures with --parallel--safe-build, instead of mangling with the file paths now uses a lock to make the package build operation thread safe and is now on by default (--parallel--safe-build is now deprecated) - by @gaborbernat (#1026)

Features

• Added temp_dir folder configuration (defaults to {toxworkdir}/.tmp) that contains tox temporary files. Package builds now create a hard link (if possible, otherwise copy - notably in case of Windows Python 2.7) to the built file, and feed that file downstream (e.g. for pip to install it). The hard link is removed at the end of the run (what it points though is kept inside distdir). This ensures that a tox session operates on the same package it built, even if a parallel tox run builds another version. Note distdir will contain only the last built package in such cases. - by @gaborbernat (#1026)

Documentation

• document tox environment recreate rules (Dependency changes and tracking) - by @gaborbernat (#93)

• document inside the --help how to disable colorized output via the PY_COLORS operating system environment variable - by @gaborbernat (#163)

• document all global tox flags and a more concise format to express default and type - by @gaborbernat (#683)

• document command line interface under the config section cli - by @gaborbernat (#829)

v3.4.0 (2018-09-20)

Bugfixes

• add --exists-action w to default pip flags to handle better VCS dependencies (pip documentation on this) - by @gaborbernat (#503)

• instead of assuming the Python version from the base python name ask the interpreter to reveal the version for the ignore_basepython_conflict flag - by @gaborbernat (#908)

• PEP-517 packaging fails with sdist already exists, fixed via ensuring the dist folder is empty before invoking the backend and pypa/setuptools 1481 - by @gaborbernat (#1003)

Features

• add commands_pre and commands_post that run before and after running the commands (setup runs always, commands only if setup succeeds, teardown always - all run until the first failing command) - by @gaborbernat (#167)

• pyproject.toml config support initially by just inline the tox.ini under tool.tox.legacy_tox_ini key; config source priority order is pyproject.toml, tox.ini and then setup.cfg - by @gaborbernat (#814)

• use the os environment variable TOX_SKIP_ENV to filter out tox environment names from the run list (set by envlist) - by @gaborbernat (#824)

• always set PIP_USER=0 (do not install into the user site package, but inside the virtual environment created) and PIP_NO_DEPS=0 (installing without dependencies can cause broken package installations) inside tox - by @gaborbernat (#838)

• tox will inject some environment variables that to indicate a command is running within tox: TOX_WORK_DIR env var is set to the tox work directory, TOX_ENV_NAME is set to the current running tox environment name, TOX_ENV_DIR is set to the current tox environments working dir - by @gaborbernat (#847)

• While running tox invokes various commands (such as building the package, pip installing dependencies and so on), these were printed in case they failed as Python arrays. Changed the representation to a shell command, allowing the users to quickly replicate/debug the failure on their own - by @gaborbernat (#851)

• skip missing interpreters value from the config file can now be overridden via the --skip-missing-interpreters cli flag - by @gaborbernat (#903)

• keep additional environments config order when listing them - by @gaborbernat (#921)

• allow injecting config value inside the ini file dependent of the fact that we’re connected to an interactive shell or not - by @gaborbernat (#947)

• do not build sdist if skip install is specified for the envs to be run - by @gaborbernat (#974)

• when verbosity level increases above two start passing through verbosity flags to pip - by @gaborbernat (#982)

• when discovering the interpreter to use check if the tox host Python matches and use that if so - by @gaborbernat (#994)

• -vv will print out why a virtual environment is re-created whenever this operation is triggered - by @gaborbernat (#1004)

Documentation

• clarify that python and pip refer to the virtual environments executable - by @gaborbernat (#305)

• add Sphinx and mkdocs example of generating documentation via tox - by @gaborbernat (#374)

• specify that setup.cfg tox configuration needs to be inside the tox:tox namespace - by @gaborbernat (#545)

v3.3.0 (2018-09-11)

Bugfixes

• fix TOX_LIMITED_SHEBANG when running under python3 - by @asottile (#931)

Features

• PEP-517 source distribution support (create a .package virtual environment to perform build operations inside) by @gaborbernat (#573)

• flit support via implementing PEP-517 by @gaborbernat (#820)

• packaging now is exposed as a hook via tox_package(session, venv) - by @gaborbernat (#951)

Miscellaneous

• Updated the VSTS build YAML to use the latest jobs and pools syntax - by @davidstaheli (#955)

v3.2.1 (2018-08-10)

Bugfixes

• --parallel--safe-build no longer cleans up its folders (distdir, distshare, log). - by @gaborbernat (#849)

v3.2.0 (2018-08-10)

Features

• Switch pip invocations to use the module -m pip instead of direct invocation. This could help avoid some of the shebang limitations. - by @gaborbernat (#935)

• Ability to specify package requirements for the tox run via the tox.ini (tox section under key requires - PEP-508 style): can be used to specify both plugin requirements or build dependencies. - by @gaborbernat (#783)

• Allow one to run multiple tox instances in parallel by providing the --parallel--safe-build flag. - by @gaborbernat (#849)

v3.1.3 (2018-08-03)

Bugfixes

• A caching issue that caused the develop-inst-nodeps action, which reinstalls the package under test, to always run has been resolved. The develop-inst-noop action, which, as the name suggests, is a no-op, will now run unless there are changes to setup.py or setup.cfg files that have not been reflected - by @stephenfin (#909)

Features

• Python version testenvs are now automatically detected instead of comparing against a hard-coded list of supported versions. This enables py38 and eventually py39 / py40 / etc. to work without requiring an upgrade to tox. As such, the following public constants are now deprecated (and scheduled for removal in tox 4.0: CPYTHON_VERSION_TUPLES, PYPY_VERSION_TUPLES, OTHER_PYTHON_INTERPRETERS, and DEFAULT_FACTORS - by @asottile (#914)

Documentation

• Add a system overview section on the index page that explains briefly how tox works - by @gaborbernat. (#867)

v3.1.2 (2018-07-12)

Bugfixes

• Revert “Fix bug with incorrectly defactorized dependencies (#772)” due to a regression ((#799)) - by @obestwalter

v3.1.1 (2018-07-09)

Bugfixes

• PyPI documentation for 3.1.0 is broken. Added test to check for this, and fix it by @gaborbernat. (#879)

v3.1.0 (2018-07-08)

Bugfixes

• Add ignore_basepython_conflict, which determines whether conflicting basepython settings for environments containing default factors, such as py27 or django18-py35, should be ignored or result in warnings. This was a common source of misconfiguration and is rarely, if ever, desirable from a user perspective - by @stephenfin (#477)

• Fix bug with incorrectly defactorized dependencies (deps passed to pip were not de-factorized) - by @bartsanchez (#706)

Features

• Add support for multiple PyPy versions using default factors. This allows you to use, for example, pypy27 knowing that the correct interpreter will be used by default - by @stephenfin (#19)

• Add support to explicitly invoke interpreter directives for environments with long path lengths. In the event that tox cannot invoke scripts with a system-limited shebang (e.x. a Linux host running a Jenkins Pipeline), a user can set the environment variable TOX_LIMITED_SHEBANG to workaround the system’s limitation (e.x. export TOX_LIMITED_SHEBANG=1) - by @jdknight (#794)

• introduce a constants module to be used internally and as experimental API - by @obestwalter (#798)

• Make py2 and py3 aliases also resolve via py on windows by @asottile. This enables the following things: tox -e py2 and tox -e py3 work on windows (they already work on posix); and setting basepython=python2 or basepython=python3 now works on windows. (#856)

• Replace the internal version parsing logic from the not well tested PEP-386 parser for the more general PEP-440. packaging >= 17.1 is now an install dependency by @gaborbernat. (#860)

Documentation

• extend the plugin documentation and make lot of small fixes and improvements - by @obestwalter (#797)

• tidy up tests - remove unused fixtures, update old cinstructs, etc. - by @obestwalter (#799)

• Various improvements to documentation: open browser once documentation generation is done, show Github/Travis info on documentation page, remove duplicate header for changelog, generate unreleased news as DRAFT on top of changelog, make the changelog page more compact and readable (width up to 1280px) by @gaborbernat (#859)

Miscellaneous

• filter out unwanted files in package - by @obestwalter (#754)

• make the already existing implicit API explicit - by @obestwalter (#800)

• improve tox quickstart and corresponding tests - by @obestwalter (#801)

• tweak codecov settings via .codecov.yml - by @obestwalter (#802)

v3.0.0 (2018-04-02)

Bugfixes

• Write directly to stdout buffer if possible to prevent str vs bytes issues - by @asottile (#426)

• fix #672 reporting to json file when skip-missing-interpreters option is used - by @r2dan (#672)

• avoid Requested Python version (X.Y) not installed stderr output when a Python environment is looked up using the py Python launcher on Windows and the environment is not found installed on the system - by @jurko-gospodnetic (#692)

• Fixed an issue where invocation of tox from the Python package, where invocation errors (failed actions) occur results in a change in the sys.stdout stream encoding in Python 3.x. New behaviour is that sys.stdout is reset back to its original encoding after invocation errors - by @tonybaloney (#723)

• The reading of command output sometimes failed with IOError: [Errno 0] Error on Windows, this was fixed by using a simpler method to update the read buffers. - by @fschulze (#727)

• (only affected rc releases) fix up tox.cmdline to be callable without args - by @gaborbernat. (#773)

• (only affected rc releases) Revert breaking change of tox.cmdline not callable with no args - by @gaborbernat. (#773)

• (only affected rc releases) fix #755 by reverting the cmdline import to the old location and changing the entry point instead - by @fschulze (#755)

Features

• tox displays exit code together with InvocationError - by @blueyed and @ederag. (#290)

• Hint for possible signal upon InvocationError, on posix systems - by @ederag and @asottile. (#766)

• Add a -q option to progressively silence tox’s output. For each time you specify -q to tox, the output provided by tox reduces. This option allows you to see only your command output without the default verbosity of what tox is doing. This also counter-acts usage of -v. For example, running tox -v -q ... will provide you with the default verbosity. tox -vv -q is equivalent to tox -v. By @sigmavirus24 (#256)

• add support for negated factor conditions, e.g. !dev: production_log - by @jurko-gospodnetic (#292)

• Headings like installed: <packages> will not be printed if there is no output to display after the :, unless verbosity is set. By @cryvate (#601)

• Allow spaces in command line options to pip in deps. Where previously only deps=-rreq.txt and deps=--requirement=req.txt worked, now also deps=-r req.txt and deps=--requirement req.txt work - by @cryvate (#668)

• drop Python 2.6 and 3.3 support: setuptools dropped supporting these, and as we depend on it we’ll follow up with doing the same (use tox <= 2.9.1 if you still need this support) - by @gaborbernat (#679)

• Add tox_runenvreport as a possible plugin, allowing the overriding of the default behaviour to execute a command to get the installed packages within a virtual environment - by @tonybaloney (#725)

• Forward PROCESSOR_ARCHITECTURE by default on Windows to fix platform.machine(). (#740)

Documentation

• Change favicon to the vector beach ball - by @hazalozturk (#748)

• Change sphinx theme to alabaster and add logo/favicon - by @hazalozturk (#639)

Miscellaneous

• Running tox without a setup.py now has a more friendly error message and gives troubleshooting suggestions - by @Volcyy. (#331)

• Fix pycodestyle (formerly pep8) errors E741 (ambiguous variable names, in this case, ‘l’s) and remove ignore of this error in tox.ini - by @cryvate (#663)

• touched up interpreters.py code and added some missing tests for it - by @jurko-gospodnetic (#708)

• The PYTHONDONTWRITEBYTECODE environment variable is no longer unset - by @stephenfin. (#744)

v2.9.1 (2017-09-29)

Miscellaneous

• integrated new release process and fixed changelog rendering for pypi.org - by @obestwalter.

v2.9.0 (2017-09-29)

Features

• tox --version now shows information about all registered plugins - by @obestwalter (#544)

Bugfixes

• skip_install overrides usedevelop (usedevelop is an option to choose the installation type if the package is installed and skip_install determines if it should be installed at all) - by @ferdonline (#571)

Miscellaneous

• #635 inherit from correct exception - by @obestwalter (#635).

• spelling and escape sequence fixes - by @scoop (#637 and #638).

• add a badge to show build status of documentation on readthedocs.io - by @obestwalter.

Documentation

• add towncrier to allow adding changelog entries with the pull requests without generating merge conflicts; with this release notes are now grouped into four distinct collections: Features, Bugfixes, Improved Documentation and Deprecations and Removals. (#614)

v2.8.2 (2017-10-09)

• #466: stop env var leakage if popen failed with resultjson or redirect

v2.8.1 (2017-09-04)

• pull request 599: fix problems with implementation of #515. Substitutions from other sections were not made anymore if they were not in envlist. Thanks to Clark Boylan (@cboylan) for helping to get this fixed (pull request 597).

v2.8.0 (2017-09-01)

• #276: Remove easy_install from docs (TL;DR: use pip). Thanks Martin Andrysík (@sifuraz).

• #301: Expand nested substitutions in tox.ini. Thanks @vlaci. Thanks to Eli Collins (@eli-collins) for creating a reproducer.

• #315: add --help and --version to helptox-quickstart. Thanks @vlaci.

• #326: Fix OSError ‘Not a directory’ when creating env on Jython 2.7.0. Thanks Nick Douma (@LordGaav).

• #429: Forward MSYSTEM by default on Windows. Thanks Marius Gedminas (@mgedmin) for reporting this.

• #449: add multi platform example to the docs. Thanks Aleks Bunin (@sashkab) and @rndr.

• #474: Start using setuptools_scm for tag based versioning.

• #484: Renamed py.test to pytest throughout the project. Thanks Slam (@3lnc).

• #504: With -a: do not show additional environments header if there are none. Thanks @rndr.

• #515: Don’t require environment variables in test environments where they are not used. Thanks André Caron (@AndreLouisCaron).

• #517: Forward NUMBER_OF_PROCESSORS by default on Windows to fix multiprocessor.cpu_count(). Thanks André Caron (@AndreLouisCaron).

• #518: Forward USERPROFILE by default on Windows. Thanks André Caron (@AndreLouisCaron).

• pull request 528: Fix some of the warnings displayed by pytest 3.1.0. Thanks Bruno Oliveira (@nicoddemus).

• pull request 547: Add regression test for #137. Thanks Martin Andrysík (@sifuraz).

• pull request 553: Add an XFAIL test to reproduce upstream bug #203. Thanks Bartolomé Sánchez Salado (@bartsanchez).

• pull request 556: Report more meaningful errors on why virtualenv creation failed. Thanks @vlaci. Also thanks to Igor Sadchenko (@igor-sadchenko) for pointing out a problem with that PR before it hit the masses ☺

• pull request 575: Add announcement doc to end all announcement docs (using only CHANGELOG and Github issues since 2.5 already).

• pull request 580: Do not ignore Sphinx warnings anymore. Thanks Bernát Gábor (@gaborbernat).

• pull request 585: Expand documentation to explain pass through of flags from deps to pip (e.g. -rrequirements.txt, -cconstraints.txt). Thanks Alexander Loechel (@loechel).

• pull request 588: Run pytest wit xfail_strict and adapt affected tests.

v2.7.0 (2017-04-02)

• pull request 450: Stop after the first installdeps and first testenv create hooks succeed. This changes the default behaviour of tox_testenv_create and tox_testenv_install_deps to not execute other registered hooks when the first hook returns a result that is not None. Thanks Anthony Sottile (@asottile).

• #271 and #464: Improve environment information for users.

  New command line parameter: -a show all defined environments - not just the ones defined in (or generated from) envlist.

  New verbosity settings for -l and -a: show user defined descriptions of the environments. This also works for generated environments from factors by concatenating factor descriptions into a complete description.

  Note that for backwards compatibility with scripts using the output of -l it’s output remains unchanged.

  Thanks Bernát Gábor (@gaborbernat).

• #464: Fix incorrect egg-info location for modified package_dir in setup.py. Thanks Selim Belhaouane (@selimb).

• #431: Add ‘LANGUAGE’ to default passed environment variables. Thanks Paweł Adamczak (@pawelad).

• #455: Add a Vagrantfile with a customized Arch Linux box for local testing. Thanks Oliver Bestwalter (@obestwalter).

• #454: Revert pull request 407, empty commands is not treated as an error. Thanks Anthony Sottile (@asottile).

• #446: (infrastructure) Travis CI tests for tox now also run on OS X now. Thanks Jason R. Coombs (@jaraco).

v2.6.0 (2017-02-04)

• add “alwayscopy” config option to instruct virtualenv to always copy files instead of symlinking. Thanks Igor Duarte Cardoso (@igordcard).

• pass setenv variables to setup.py during a usedevelop install. Thanks Eli Collins (@eli-collins).

• replace all references to testrun.org with readthedocs ones. Thanks Oliver Bestwalter (@obestwalter).

• fix #323 by avoiding virtualenv14 is not used on py32 (although we don’t officially support py32). Thanks Jason R. Coombs (@jaraco).

• add Python 3.6 to envlist and CI. Thanks Andrii Soldatenko (@andriisoldatenko).

• fix glob resolution from TOX_TESTENV_PASSENV env variable Thanks Allan Feldman (@a-feld).

v2.5.0 (2016-11-16)

• slightly backward incompatible: fix #310: the {posargs} substitution now properly preserves the tox command line positional arguments. Positional arguments with spaces are now properly handled. NOTE: if your tox invocation previously used extra quoting for positional arguments to work around #310, you need to remove the quoting. Example: tox – “‘some string’” # has to now be written simply as tox – “some string” thanks holger krekel. You can set minversion = 2.5.0 in the [tox] section of tox.ini to make sure people using your tox.ini use the correct version.

• fix #359: add COMSPEC to default passenv on windows. Thanks @anthrotype.

• add support for py36 and py37 and add py36-dev and py37(nightly) to travis builds of tox. Thanks John Vandenberg.

• fix #348: add py2 and py3 as default environments pointing to “python2” and “python3” basepython executables. Also fix #347 by updating the list of default envs in the tox basic example. Thanks Tobias McNulty.

• make “-h” and “–help-ini” options work even if there is no tox.ini, thanks holger krekel.

• add {:} substitution, which is replaced with os-specific path separator, thanks Lukasz Rogalski.

• fix #305: downloadcache test env config is now ignored as pip-8 does caching by default. Thanks holger krekel.

• output from install command in verbose (-vv) mode is now printed to console instead of being redirected to file, thanks Lukasz Rogalski

• fix #399. Make sure {envtmpdir} is created if it doesn’t exist at the start of a testenvironment run. Thanks Manuel Jacob.

• fix #316: Lack of commands key in ini file is now treated as an error. Reported virtualenv status is ‘nothing to do’ instead of ‘commands succeeded’, with relevant error message displayed. Thanks Lukasz Rogalski.

v2.4.1 (2016-10-12)

• fix #380: properly perform substitution again. Thanks Ian Cordasco.

v2.4.0 (2016-10-12)

• remove PYTHONPATH from environment during the install phase because a tox-run should not have hidden dependencies and the test commands will also not see a PYTHONPATH. If this causes unforeseen problems it may be reverted in a bugfix release. Thanks Jason R. Coombs.

• fix #352: prevent a configuration where envdir==toxinidir and refine docs to warn people about changing “envdir”. Thanks Oliver Bestwalter and holger krekel.

• fix #375, fix #330: warn against tox-setup.py integration as “setup.py test” should really just test with the current interpreter. Thanks Ronny Pfannschmidt.

• fix #302: allow cross-testenv substitution where we substitute with {x,y} generative syntax. Thanks Andrew Pashkin.

• fix #212: allow escaping curly brace chars “{” and “}” if you need the chars “{” and “}” to appear in your commands or other ini values. Thanks John Vandenberg.

• addresses #66: add –workdir option to override where tox stores its “.tox” directory and all of the virtualenv environment. Thanks Danring.

• introduce per-venv list_dependencies_command which defaults to “pip freeze” to obtain the list of installed packages. Thanks Ted Shaw, Holger Krekel.

• close #66: add documentation to jenkins page on how to avoid “too long shebang” lines when calling pip from tox. Note that we can not use “python -m pip install X” by default because the latter adds the CWD and pip will think X is installed if it is there. “pip install X” does not do that.

• new list_dependencies_command to influence how tox determines which dependencies are installed in a testenv.

• (experimental) New feature: When a search for a config file fails, tox tries loading setup.cfg with a section prefix of “tox”.

• fix #275: Introduce hooks tox_runtest_pre` and tox_runtest_post which run before and after the tests of a venv, respectively. Thanks to Matthew Schinckel and itxaka serrano.

• fix #317: evaluate minversion before tox config is parsed completely. Thanks Sachi King for the PR.

• added the “extras” environment option to specify the extras to use when doing the sdist or develop install. Contributed by Alex Grönholm.

• use pytest-catchlog instead of pytest-capturelog (latter is not maintained, uses deprecated pytest API)

v2.3.2 (2016-02-11)

• fix #314: fix command invocation with .py scripts on windows.

• fix #279: allow cross-section substitution when the value contains posargs. Thanks Sachi King for the PR.

v2.3.1 (2015-12-14)

• fix #294: re-allow cross-section substitution for setenv.

v2.3.0 (2015-12-09)

• DEPRECATE use of “indexservers” in tox.ini. It complicates the internal code and it is recommended to rather use the devpi system for managing indexes for pip.

• fix #285: make setenv processing fully lazy to fix regressions of tox-2.2.X and so that we can now have testenv attributes like “basepython” depend on environment variables that are set in a setenv section. Thanks Nelfin for some tests and initial work on a PR.

• allow “#” in commands. This is slightly incompatible with commands sections that used a comment after a “" line continuation. Thanks David Stanek for the PR.

• fix #289: fix build_sphinx target, thanks Barry Warsaw.

• fix #252: allow environment names with special characters. Thanks Julien Castets for initial PR and patience.

• introduce experimental tox_testenv_create(venv, action) and tox_testenv_install_deps(venv, action) hooks to allow plugins to do additional work on creation or installing deps. These hooks are experimental mainly because of the involved “venv” and session objects whose current public API is not fully guaranteed.

• internal: push some optional object creation into tests because tox core doesn’t need it.

v2.2.1 (2015-12-09)

• fix bug where {envdir} substitution could not be used in setenv if that env value is then used in {basepython}. Thanks Florian Bruhin.

v2.2.0 (2015-11-11)

• fix #265 and add LD_LIBRARY_PATH to passenv on linux by default because otherwise the python interpreter might not start up in certain configurations (redhat software collections). Thanks David Riddle.

• fix #246: fix regression in config parsing by reordering such that {envbindir} can be used again in tox.ini. Thanks Olli Walsh.

• fix #99: the {env:…} substitution now properly uses environment settings from the setenv section. Thanks Itxaka Serrano.

• fix #281: make –force-dep work when urls are present in dependency configs. Thanks Glyph Lefkowitz for reporting.

• fix #174: add new ignore_outcome testenv attribute which can be set to True in which case it will produce a warning instead of an error on a failed testenv command outcome. Thanks Rebecka Gulliksson for the PR.

• fix #280: properly skip missing interpreter if {envsitepackagesdir} is present in commands. Thanks BB:ceridwenv

v2.1.1 (2015-06-23)

• fix platform skipping for detox

• report skipped platforms as skips in the summary

v2.1.0 (2015-06-19)

• fix #258, fix #248, fix #253: for non-test commands (installation, venv creation) we pass in the full invocation environment.

• remove experimental –set-home option which was hardly used and hackily implemented (if people want home-directory isolation we should figure out a better way to do it, possibly through a plugin)

• fix #259: passenv is now a line-list which allows interspersing comments. Thanks stefano-m.

• allow envlist to be a multi-line list, to intersperse comments and have long envlist settings split more naturally. Thanks Andre Caron.

• introduce a TOX_TESTENV_PASSENV setting which is honored when constructing the set of environment variables for test environments. Thanks Marc Abramowitz for pushing in this direction.

v2.0.2 (2015-06-03)

• fix #247: tox now passes the LANG variable from the tox invocation environment to the test environment by default.

• add SYSTEMDRIVE into default passenv on windows to allow pip6 to work. Thanks Michael Krause.

v2.0.1 (2015-05-13)

• fix wheel packaging to properly require argparse on py26.

v2.0.0 (2015-05-12)

• (new) introduce environment variable isolation: tox now only passes the PATH and PIP_INDEX_URL variable from the tox invocation environment to the test environment and on Windows also SYSTEMROOT, PATHEXT, TEMP and TMP whereas on unix additionally TMPDIR is passed. If you need to pass through further environment variables you can use the new passenv setting, a space-separated list of environment variable names. Each name can make use of fnmatch-style glob patterns. All environment variables which exist in the tox-invocation environment will be copied to the test environment.

• a new --help-ini option shows all possible testenv settings and their defaults.

• (new) introduce a way to specify on which platform a testenvironment is to execute: the new per-venv “platform” setting allows one to specify a regular expression which is matched against sys.platform. If platform is set and doesn’t match the platform spec in the test environment the test environment is ignored, no setup or tests are attempted.

• (new) add per-venv “ignore_errors” setting, which defaults to False.

  If True, a non-zero exit code from one command will be ignored and further commands will be executed (which was the default behavior in tox < 2.0). If False (the default), then a non-zero exit code from one command will abort execution of commands for that environment.

• show and store in json the version dependency information for each venv

• remove the long-deprecated “distribute” option as it has no effect these days.

• fix #233: avoid hanging with tox-setuptools integration example. Thanks simonb.

• fix #120: allow substitution for the commands section. Thanks Volodymyr Vitvitski.

• fix #235: fix AttributeError with –installpkg. Thanks Volodymyr Vitvitski.

• tox has now somewhat pep8 clean code, thanks to Volodymyr Vitvitski.

• fix #240: allow one to specify empty argument list without it being rewritten to “.”. Thanks Daniel Hahler.

• introduce experimental (not much documented yet) plugin system based on pytest’s externalized “pluggy” system. See tox/hookspecs.py for the current hooks.

• introduce parser.add_testenv_attribute() to register an ini-variable for testenv sections. Can be used from plugins through the tox_add_option hook.

• rename internal files – tox offers no external API except for the experimental plugin hooks, use tox internals at your own risk.

• DEPRECATE distshare in documentation

v1.9.2 (2015-03-23)

• backout ability that –force-dep substitutes name/versions in requirement files due to various issues. This fixes #228, fixes #230, fixes #231 which popped up with 1.9.1.

v1.9.1 (2015-03-23)

• use a file instead of a pipe for command output in “–result-json”. Fixes some termination issues with python2.6.

• allow –force-dep to override dependencies in “-r” requirements files. Thanks Sontek for the PR.

• fix #227: use “-m virtualenv” instead of “-mvirtualenv” to make it work with pyrun. Thanks Marc-Andre Lemburg.

v1.9.0 (2015-02-24)

• fix #193: Remove --pre from the default install_command; by default tox will now only install final releases from PyPI for unpinned dependencies. Use pip_pre = true in a testenv or the --pre command-line option to restore the previous behavior.

• fix #199: fill resultlog structure ahead of virtualenv creation

• refine determination if we run from Jenkins, thanks Borge Lanes.

• echo output to stdout when --report-json is used

• fix #11: add a skip_install per-testenv setting which prevents the installation of a package. Thanks Julian Krause.

• fix #124: ignore command exit codes; when a command has a “-” prefix, tox will ignore the exit code of that command

• fix #198: fix broken envlist settings, e.g. {py26,py27}{-lint,}

• fix #191: lessen factor-use checks

v1.8.1 (2014-10-24)

• fix #190: allow setenv to be empty.

• allow escaping curly braces with “". Thanks Marc Abramowitz for the PR.

• allow “.” names in environment names such that “py27-django1.7” is a valid environment name. Thanks Alex Gaynor and Alex Schepanovski.

• report subprocess exit code when execution fails. Thanks Marius Gedminas.

v1.8.0 (2014-09-24)

• new multi-dimensional configuration support. Many thanks to Alexander Schepanovski for the complete PR with docs. And to Mike Bayer and others for testing and feedback.

• fix #148: remove “__PYVENV_LAUNCHER__” from os.environ when starting subprocesses. Thanks Steven Myint.

• fix #152: set VIRTUAL_ENV when running test commands, thanks Florian Ludwig.

• better report if we can’t get version_info from an interpreter executable. Thanks Floris Bruynooghe.

v1.7.2 (2014-07-15)

• fix #150: parse {posargs} more like we used to do it pre 1.7.0. The 1.7.0 behaviour broke a lot of OpenStack projects. See PR85 and the issue discussions for (far) more details, hopefully resulting in a more refined behaviour in the 1.8 series. And thanks to Clark Boylan for the PR.

• fix #59: add a config variable skip-missing-interpreters as well as command line option --skip-missing-interpreters which won’t fail the build if Python interpreters listed in tox.ini are missing. Thanks Alexandre Conrad for PR104.

• fix #164: better traceback info in case of failing test commands. Thanks Marc Abramowitz for PR92.

• support optional env variable substitution, thanks Morgan Fainberg for PR86.

• limit python hashseed to 1024 on Windows to prevent possible memory errors. Thanks March Schlaich for the PR90.

v1.7.1 (2014-03-28)

• fix #162: don’t list python 2.5 as compatible/supported

• fix #158 and fix #155: windows/virtualenv properly works now: call virtualenv through “python -m virtualenv” with the same interpreter which invoked tox. Thanks Chris Withers, Ionel Maries Cristian.

v1.7.0 (2014-01-29)

• don’t lookup “pip-script” anymore but rather just “pip” on windows as this is a pip implementation detail and changed with pip-1.5. It might mean that tox-1.7 is not able to install a different pip version into a virtualenv anymore.

• drop Python2.5 compatibility because it became too hard due to the setuptools-2.0 dropping support. tox now has no support for creating python2.5 based environments anymore and all internal special-handling has been removed.

• merged PR81: new option –force-dep which allows one to override tox.ini specified dependencies in setuptools-style. For example “–force-dep ‘django<1.6’” will make sure that any environment using “django” as a dependency will get the latest 1.5 release. Thanks Bruno Oliveria for the complete PR.

• merged PR125: tox now sets “PYTHONHASHSEED” to a random value and offers a “–hashseed” option to repeat a test run with a specific seed. You can also use –hashsheed=noset to instruct tox to leave the value alone. Thanks Chris Jerdonek for all the work behind this.

• fix #132: removing zip_safe setting (so it defaults to false) to allow installation of tox via easy_install/eggs. Thanks Jenisys.

• fix #126: depend on virtualenv>=1.11.2 so that we can rely (hopefully) on a pip version which supports –pre. (tox by default uses to –pre). also merged in PR84 so that we now call “virtualenv” directly instead of looking up interpreters. Thanks Ionel Maries Cristian. This also fixes #140.

• fix #130: you can now set install_command=easy_install {opts} {packages} and expect it to work for repeated tox runs (previously it only worked when always recreating). Thanks jenisys for precise reporting.

• fix #129: tox now uses Popen(…, universal_newlines=True) to force creation of unicode stdout/stderr streams. fixes a problem on specific platform configs when creating virtualenvs with Python3.3. Thanks Jorgen Schäfer or investigation and solution sketch.

• fix #128: enable full substitution in install_command, thanks for the PR to Ronald Evers

• rework and simplify “commands” parsing and in particular posargs substitutions to avoid various win32/posix related quoting issues.

• make sure that the –installpkg option trumps any usedevelop settings in tox.ini or

• introduce –no-network to tox’s own test suite to skip tests requiring networks

• introduce –sitepackages to force sitepackages=True in all environments.

• fix #105 – don’t depend on an existing HOME directory from tox tests.

v1.6.1 (2013-09-04)

• fix #119: {envsitepackagesdir} is now correctly computed and has a better test to prevent regression.

• fix #116: make 1.6 introduced behaviour of changing to a per-env HOME directory during install activities dependent on “–set-home” for now. Should re-establish the old behaviour when no option is given.

• fix #118: correctly have two tests use realpath(). Thanks Barry Warsaw.

• fix test runs on environments without a home directory (in this case we use toxinidir as the homedir)

• fix #117: python2.5 fix: don’t use --insecure option because its very existence depends on presence of “ssl”. If you want to support python2.5/pip1.3.1 based test environments you need to install ssl and/or use PIP_INSECURE=1 through setenv. section.

• fix #102: change to {toxinidir} when installing dependencies. This allows one to use relative path like in “-rrequirements.txt”.

v1.6.0 (2013-08-15)

• fix #35: add new EXPERIMENTAL “install_command” testenv-option to configure the installation command with options for dep/pkg install. Thanks Carl Meyer for the PR and docs.

• fix #91: python2.5 support by vendoring the virtualenv-1.9.1 script and forcing pip<1.4. Also the default [py25] environment modifies the default installer_command (new config option) to use pip without the “–pre” option which was introduced with pip-1.4 and is now required if you want to install non-stable releases. (tox defaults to install with “–pre” everywhere).

• during installation of dependencies HOME is now set to a pseudo location ({envtmpdir}/pseudo-home). If an index url was specified a .pydistutils.cfg file will be written with an index_url setting so that packages defining setup_requires dependencies will not silently use your HOME-directory settings or PyPI.

• fix #1: empty setup files are properly detected, thanks Anthon van der Neuth

• remove toxbootstrap.py for now because it is broken.

• fix #109 and fix #111: multiple “-e” options are now combined (previously the last one would win). Thanks Anthon van der Neut.

• add –result-json option to write out detailed per-venv information into a json report file to be used by upstream tools.

• add new config options usedevelop and skipsdist as well as a command line option --develop to install the package-under-test in develop mode. thanks Monty Tailor for the PR.

• always unset PYTHONDONTWRITEBYTE because newer setuptools doesn’t like it

• if a HOMEDIR cannot be determined, use the toxinidir.

• refactor interpreter information detection to live in new tox/interpreters.py file, tests in tests/test_interpreters.py.

v1.5.0 (2013-06-22)

• fix #104: use setuptools by default, instead of distribute, now that setuptools has distribute merged.

• make sure test commands are searched first in the virtualenv

• re-fix #2 - add whitelist_externals to be used in [testenv*] sections, allowing to avoid warnings for commands such as make, used from the commands value.

• fix #97 - allow substitutions to reference from other sections (thanks Krisztian Fekete)

• fix #92 - fix {envsitepackagesdir} to actually work again

• show (test) command that is being executed, thanks Lukasz Balcerzak

• re-license tox to MIT license

• depend on virtualenv-1.9.1

• rename README.txt to README.rst to make bitbucket happier

v1.4.3 (2013-02-28)

• use pip-script.py instead of pip.exe on win32 to avoid the lock exe file on execution issue (thanks Philip Thiem)

• introduce -l|–listenv option to list configured environments (thanks Lukasz Balcerzak)

• fix downloadcache determination to work according to docs: Only make pip use a download cache if PIP_DOWNLOAD_CACHE or a downloadcache=PATH testenv setting is present. (The ENV setting takes precedence)

• fix #84 - pypy on windows creates a bin not a scripts venv directory (thanks Lukasz Balcerzak)

• experimentally introduce –installpkg=PATH option to install a package rather than create/install an sdist package. This will still require and use tox.ini and tests from the current working dir (and not from the remote package).

• substitute {envsitepackagesdir} with the package installation directory (closes #72) (thanks g2p)

• issue #70 remove PYTHONDONTWRITEBYTECODE workaround now that virtualenv behaves properly (thanks g2p)

• merged tox-quickstart command, contributed by Marc Abramowitz, which generates a default tox.ini after asking a few questions

• fix #48 - win32 detection of pypy and other interpreters that are on PATH (thanks Gustavo Picon)

• fix grouping of index servers, it is now done by name instead of indexserver url, allowing to use it to separate dependencies into groups even if using the same default indexserver.

• look for “tox.ini” files in parent dirs of current dir (closes #34)

• the “py” environment now by default uses the current interpreter (sys.executable) make tox’ own setup.py test execute tests with it (closes #46)

• change tests to not rely on os.path.expanduser (closes #60), also make mock session return args[1:] for more precise checking (closes #61) thanks to Barry Warsaw for both.

v1.4.2 (2012-07-20)

• fix some tests which fail if /tmp is a symlink to some other place

• “python setup.py test” now runs tox tests via tox :) also added an example on how to do it for your project.

v1.4.1 (2012-07-03)

• fix #41 better quoting on windows - you can now use “<” and “>” in deps specifications, thanks Chris Withers for reporting

v1.4 (2012-06-13)

• fix #26 - no warnings on absolute or relative specified paths for commands

• fix #33 - commentchars are ignored in key-value settings allowing for specifying commands like: python -c “import sys ; print sys” which would formerly raise irritating errors because the “;” was considered a comment

• tweak and improve reporting

• refactor reporting and virtualenv manipulation to be more accessible from 3rd party tools

• support value substitution from other sections with the {[section]key} syntax

• fix #29 - correctly point to pytest explanation for importing modules fully qualified

• fix #32 - use –system-site-packages and don’t pass –no-site-packages

• add python3.3 to the default env list, so early adopters can test

• drop python2.4 support (you can still have your tests run on

• fix the links/checkout howtos in the docs python-2.4, just tox itself requires 2.5 or higher.

v1.3 2011-12-21

• fix: allow one to specify wildcard filesystem paths when specifying dependencies such that tox searches for the highest version

• fix issue #21: clear PIP_REQUIRES_VIRTUALENV which avoids pip installing to the wrong environment, thanks to bb’s streeter

• make the install step honour a testenv’s setenv setting (thanks Ralf Schmitt)

v1.2 2011-11-10

• remove the virtualenv.py that was distributed with tox and depend on >=virtualenv-1.6.4 (possible now since the latter fixes a few bugs that the inlining tried to work around)

• fix #10: work around UnicodeDecodeError when invoking pip (thanks Marc Abramowitz)

• fix a problem with parsing {posargs} in tox commands (spotted by goodwill)

• fix the warning check for commands to be installed in testenvironment (thanks Michael Foord for reporting)

v1.1 (2011-07-08)

• fix #5 - don’t require argparse for python versions that have it

• fix #6 - recreate virtualenv if installing dependencies failed

• fix #3 - fix example on frontpage

• fix #2 - warn if a test command does not come from the test environment

• fixed/enhanced: except for initial install always call “-U –no-deps” for installing the sdist package to ensure that a package gets upgraded even if its version number did not change. (reported on TIP mailing list and IRC)

• inline virtualenv.py (1.6.1) script to avoid a number of issues, particularly failing to install python3 environments from a python2 virtualenv installation.

• rework and enhance docs for display on readthedocs.org

v1.0

• move repository and toxbootstrap links to https://bitbucket.org/hpk42/tox

• fix #7: introduce a “minversion” directive such that tox bails out if it does not have the correct version.

• fix #24: introduce a way to set environment variables for for test commands (thanks Chris Rose)

• fix #22: require virtualenv-1.6.1, obsoleting virtualenv5 (thanks Jannis Leidel) and making things work with pypy-1.5 and python3 more seamlessly

• toxbootstrap.py (used by jenkins build agents) now follows the latest release of virtualenv

• fix #20: document format of URLs for specifying dependencies

• fix #19: substitute Hudson for Jenkins everywhere following the renaming of the project. NOTE: if you used the special [tox:hudson] section it will now need to be named [tox:jenkins].

• fix issue 23 / apply some ReST fixes

• change the positional argument specifier to use {posargs:} syntax and fix issues #15 and #10 by refining the argument parsing method (Chris Rose)

• remove use of inipkg lazy importing logic - the namespace/imports are anyway very small with tox.

• fix a fspath related assertion to work with debian installs which uses symlinks

• show path of the underlying virtualenv invocation and bootstrap virtualenv.py into a working subdir

• added a CONTRIBUTORS file

v0.9

• fix pip-installation mixups by always unsetting PIP_RESPECT_VIRTUALENV (thanks Armin Ronacher)

• #1: Add a toxbootstrap.py script for tox, thanks to Sridhar Ratnakumar

• added support for working with different and multiple PyPI indexservers.

• new option: -r|–recreate to force recreation of virtualenv

• depend on py>=1.4.0 which does not contain or install the py.test anymore which is now a separate distribution “pytest”.

• show logfile content if there is an error (makes CI output more readable)

v0.8

• work around a virtualenv limitation which crashes if PYTHONDONTWRITEBYTECODE is set.

• run pip/easy installs from the environment log directory, avoids naming clashes between env names and dependencies (thanks ronny)

• require a more recent version of py lib

• refactor and refine config detection to work from a single file and to detect the case where a python installation overwrote an old one and resulted in a new executable. This invalidates the existing virtualenvironment now.

• change all internal source to strip trailing whitespaces

v0.7

• use virtualenv5 (my own fork of virtualenv3) for now to create python3 environments, fixes a couple of issues and makes tox more likely to work with Python3 (on non-windows environments)

• add sitepackages option for testenv sections so that environments can be created with access to globals (default is not to have access, i.e. create environments with --no-site-packages.

• addressing #4: always prepend venv-path to PATH variable when calling subprocesses

• fix #2: exit with proper non-zero return code if there were errors or test failures.

• added unittest2 examples contributed by Michael Foord

• only allow ‘True’ or ‘False’ for boolean config values (lowercase / uppercase is irrelevant)

• recreate virtualenv on changed configurations

v0.6

• fix OSX related bugs that could cause the caller’s environment to get screwed (sorry). tox was using the same file as virtualenv for tracking the Python executable dependency and there also was confusion wrt links. this should be fixed now.

• fix long description, thanks Michael Foord

v0.5

• initial release

tox plugins

New in version 2.0.

A growing number of hooks make tox modifiable in different phases of execution by writing plugins.

tox - like pytest and devpi - uses pluggy to provide an extension mechanism for pip-installable internal or devpi/PyPI-published plugins.

Using plugins

To start using a plugin you need to install it in the same environment where the tox host is installed.

e.g.:

$ pip install tox-travis

You can search for available plugins on PyPI by visiting PyPI and searching for packages that are prefixed tox- or contain the word “plugin” in the description. Examples include:

tox-ansible                          - Plugin for generating tox environments for tools like ansible-test
tox-asdf                             - A tox plugin that finds python executables using asdf
tox-backticks                        - Allows backticks within setenv blocks for populating
                                       environment variables
tox-bindep                           - Runs bindep checks prior to tests
tox-bitbucket-status                 - Update bitbucket status for each env
tox-cmake                            - Build CMake projects using tox
tox-conda                            - Provides integration with the condo package manager
tox-current-env                      - Run tests in the current python environment
tox-docker                           - Launch a docker instance around test runs
tox-direct                           - Run everything directly without tox venvs
tox-envlist                          - Allows selection of a different tox envlist
tox-envreport                        - A tox-plugin to document the setup of used virtual
tox-factor                           - Runs a subset of tox test environments
tox-globinterpreter                  - tox plugin to allow specification of interpreter
tox-gh-actions                       - A plugin for helping to run tox in GitHub actions.
tox-ltt                              - Light-the-torch integration
tox-no-internet                      - Workarounds for using tox with no internet connection
tox-pdm                              - Utilizes PDM as the package manager and installer
tox-pip-extensions                   - Augment tox with different installation methods via
                                       progressive enhancement.
tox-pipenv                           - A pipenv plugin for tox
tox-pipenv-install                   - Install packages from Pipfile
tox-poetry                           - Install packages using poetry
tox-py-backwards                     - tox plugin for py-backwards
tox-pyenv                            - tox plugin that makes tox use ``pyenv which`` to find
                                       python executables
tox-pytest-summary                   - tox + Py.test summary
tox-run-before                       - tox plugin to run shell commands before the test
                                       environments are created.
tox-run-command                      - tox plugin to run arbitrary commands in a virtualenv
tox-tags                             - Allows running subsets of environments based on tags
tox-travis                           - Seamless integration of tox into Travis CI
tox-venv                             - Use python3 venvs for python3 tox testenvs environments.
tox-virtualenv-no-download           - Disable virtualenv's download-by-default in tox

There might also be some plugins not (yet) available from PyPI that could be installed directly from source hosters like Github or Bitbucket (or from a local clone). See the associated pip documentation.

To see what is installed you can call tox --version to get the version of the host and names and locations of all installed plugins:

3.0.0 imported from /home/ob/.virtualenvs/tmp/lib/python3.6/site-packages/tox/__init__.py
registered plugins:
    tox-travis-0.10 at /home/ob/.virtualenvs/tmp/lib/python3.6/site-packages/tox_travis/hooks.py

Creating a plugin

Start from a template

You can create a new tox plugin with all the bells and whistles via a Cookiecutter template (see cookiecutter-tox-plugin - this will create a complete PyPI-releasable, documented project with license, documentation and CI.

$ pip install -U cookiecutter
$ cookiecutter gh:tox-dev/cookiecutter-tox-plugin

Tutorial: a minimal tox plugin

Note

This is the minimal implementation to demonstrate what is absolutely necessary to have a working plugin for internal use. To move from something like this to a publishable plugin you could apply cookiecutter -f cookiecutter-tox-plugin and adapt the code to the package based structure used in the cookiecutter.

Let us consider you want to extend tox behaviour by displaying fireworks at the end of a successful tox run (we won’t go into the details of how to display fireworks though).

To create a working plugin you need at least a python project with a tox entry point and a python module implementing one or more of the pluggy-based hooks tox specifies (using the @tox.hookimpl decorator as marker).

minimal structure:

$ mkdir tox-fireworks
$ cd tox-fireworks
$ touch tox_fireworks.py
$ touch setup.py

contents of tox_fireworks.py:

import pluggy

hookimpl = pluggy.HookimplMarker("tox")


@hookimpl
def tox_addoption(parser):
    """Add command line option to display fireworks on request."""


@hookimpl
def tox_configure(config):
    """Post process config after parsing."""


@hookimpl
def tox_runenvreport(config):
    """Display fireworks if all was fine and requested."""

Note

See Hook specifications and related API for details

contents of setup.py:

from setuptools import setup

setup(
    name="tox-fireworks",
    py_modules=["tox_fireworks"],
    entry_points={"tox": ["fireworks = tox_fireworks"]},
    classifiers=["Framework:: tox"],
)

Using the tox- prefix in tox-fireworks is an established convention to be able to see from the project name that this is a plugin for tox. It also makes it easier to find with e.g. pip search 'tox-' once it is released on PyPI.

To make your new plugin discoverable by tox, you need to install it. During development you should install it with -e or --editable, so that changes to the code are immediately active:

$ pip install -e </path/to/tox-fireworks>

Publish your plugin to PyPI

If you think the rest of the world could profit using your plugin, you can publish it to PyPI.

You need to add some more meta data to setup.py (see cookiecutter-tox-plugin for a complete example or consult the setup.py docs).

Note

Make sure your plugin project name is prefixed by tox- to be easy to find via e.g. pip search tox-

You can and publish it like:

$ cd </path/to/tox-fireworks>
$ python setup.py sdist bdist_wheel upload

Note

You could also use twine for secure uploads.

For more information about packaging and deploying Python projects see the Python Packaging Guide.

Hook specifications and related API

Hook specifications for tox - see https://pluggy.readthedocs.io/

tox.hookspecs.tox_addoption(parser)

add command line options to the argparse-style parser object.

tox.hookspecs.tox_cleanup(session)

Called just before the session is destroyed, allowing any final cleanup operation

tox.hookspecs.tox_configure(config)

Called after command line options are parsed and ini-file has been read.

Please be aware that the config object layout may change between major tox versions.

tox.hookspecs.tox_get_python_executable(envconfig)

Return a python executable for the given python base name.

The first plugin/hook which returns an executable path will determine it.

envconfig is the testenv configuration which contains per-testenv configuration, notably the .envname and .basepython setting.

tox.hookspecs.tox_package(session, venv)

Return the package to be installed for the given venv.

Called once for every environment.

tox.hookspecs.tox_runenvreport(venv, action)

Get the installed packages and versions in this venv.

This could be used for alternative (ie non-pip) package managers, this plugin should return a list of type str

tox.hookspecs.tox_runtest(venv, redirect)

Run the tests for this venv.

Note

This hook uses firstresult=True (see pluggy first result only) – hooks implementing this will be run until one returns non-None.

tox.hookspecs.tox_runtest_post(venv)

Perform arbitrary action after running tests for this venv.

This could be used to have per-venv test reporting of pass/fail status.

tox.hookspecs.tox_runtest_pre(venv)

Perform arbitrary action before running tests for this venv.

This could be used to indicate that tests for a given venv have started, for instance.

tox.hookspecs.tox_testenv_create(venv, action)

Perform creation action for this venv.

Some example usage:

• To add behavior but still use tox’s implementation to set up a virtualenv, implement this hook but do not return a value (or explicitly return None).

• To override tox’s virtualenv creation, implement this hook and return a non-None value.

Note

This api is experimental due to the unstable api of tox.venv.VirtualEnv.

Note

This hook uses firstresult=True (see pluggy first result only) – hooks implementing this will be run until one returns non-None.

tox.hookspecs.tox_testenv_install_deps(venv, action)

Perform install dependencies action for this venv.

Some example usage:

• To add behavior but still use tox’s implementation to install dependencies, implement this hook but do not return a value (or explicitly return None). One use-case may be to install (or ensure) non-python dependencies such as debian packages.

• To override tox’s installation of dependencies, implement this hook and return a non-None value. One use-case may be to install via a different installation tool such as pip-accel or pip-faster.

Note

This api is experimental due to the unstable api of tox.venv.VirtualEnv.

Note

This hook uses firstresult=True (see pluggy first result only) – hooks implementing this will be run until one returns non-None.

class tox.config.Parser

Command line and ini-parser control object.

add_argument(*args, **kwargs)

add argument to command line parser. This takes the same arguments that argparse.ArgumentParser.add_argument.

add_testenv_attribute(name, type, help, default=None, postprocess=None)

add an ini-file variable for “testenv” section.

Types are specified as strings like “bool”, “line-list”, “string”, “argv”, “path”, “argvlist”.

The postprocess function will be called for each testenv like postprocess(testenv_config=testenv_config, value=value) where value is the value as read from the ini (or the default value) and testenv_config is a tox.config.TestenvConfig instance which will receive all ini-variables as object attributes.

Any postprocess function must return a value which will then be set as the final value in the testenv section.

add_testenv_attribute_obj(obj)

add an ini-file variable as an object.

This works as the add_testenv_attribute function but expects “name”, “type”, “help”, and “postprocess” attributes on the object.

class tox.config.Config

Global Tox config object.

args

option namespace containing all parsed command line options

envconfigs

Mapping envname -> envconfig

class tox.config.TestenvConfig

Testenv Configuration object.

In addition to some core attributes/properties this config object holds all per-testenv ini attributes as attributes, see “tox –help-ini” for an overview.

config

global tox config object

envname

test environment name

property envpython

Path to python executable.

factors

set of factors

get_envbindir()

Path to directory where scripts/binaries reside.

get_envpython()

path to python/jython executable.

get_envsitepackagesdir()

Return sitepackagesdir of the virtualenv environment.

NOTE: Only available during execution, not during parsing.

property python_info

Return sitepackagesdir of the virtualenv environment.

class tox.venv.VirtualEnv

getcommandpath(name, venv=True, cwd=None)

Return absolute path (str or localpath) for specified command name.

• If it’s a local path we will rewrite it as as a relative path.

• If venv is True we will check if the command is coming from the venv or is allowed to come from external.

property name

test environment name.

property path

Path to environment base dir.

update(action)

return status string for updating actual venv to match configuration. if status string is empty, all is ok.

class tox.session.Session

The session object that ties together configuration, reporting, venv creation, testing.

Developers FAQ

This section contains information for users who want to extend the tox source code.

PyCharm

1. To generate the project interpreter you can use tox -rvvve dev.

2. For tests we use pytest, therefore change the Default test runner to pytest.

3. In order to be able to debug tests which create a virtual environment (the ones in test_z_cmdline.py) one needs to disable the PyCharm feature Attach to subprocess automatically while debugging (because virtualenv creation calls via subprocess to the pip executable, and PyCharm rewrites all calls to Python interpreters to attach to its debugger - however, this rewrite for pip makes it to have bad arguments: no such option --port).

Multiple Python versions on Windows

In order to run the unit tests locally all Python versions enlisted in tox.ini need to be installed.

Note

For a nice Windows terminal take a look at cmder.

One solution for this is to install the latest conda, and then install all Python versions via conda envs. This will create separate folders for each Python version.

conda create -n python2.7 python=2.7 anaconda

For tox to find them you’ll need to:

• add the main installation version to the systems PATH variable (e.g. D:\Anaconda - you can use WindowsPathEditor)

• for other versions create a BAT scripts into the main installation folder to delegate the call to the correct Python interpreter:

  @echo off
  REM python2.7.bat
  @D:\Anaconda\pkgs\python-2.7.13-1\python.exe %*
  

This way you can also directly call from cli the matching Python version if you need to(similarly to UNIX systems), for example:

python2.7 main.py
python3.6 main.py

Writing a JSON result file

You can instruct tox to write a json-report file via:

tox --result-json=PATH

This will create a json-formatted result file using this schema:

{
  "testenvs": {
    "py27": {
      "python": {
        "executable": "/home/hpk/p/tox/.tox/py27/bin/python",
        "version": "2.7.3 (default, Aug  1 2012, 05:14:39) \n[GCC 4.6.3]",
        "version_info": [ 2, 7, 3, "final", 0 ]
      },
      "test": [
        {
          "output": "...",
          "command": [
            "/home/hpk/p/tox/.tox/py27/bin/pytest",
            "--instafail",
            "--junitxml=/home/hpk/p/tox/.tox/py27/log/junit-py27.xml",
            "tests/test_config.py"
          ],
          "retcode": "0"
        }
      ],
      "setup": []
    }
  },
  "platform": "linux2",
  "installpkg": {
    "basename": "tox-1.6.0.dev1.zip",
    "sha256": "b6982dde5789a167c4c35af0d34ef72176d0575955f5331ad04aee9f23af4326"
  },
  "toxversion": "1.6.0.dev1",
  "reportversion": "1"
}

Less announcing, more change-logging

With version 2.5.0 we dropped creating special announcement documents and rely on communicating all relevant changes through the CHANGELOG. See at PyPI for a rendered version of the last changes containing links to the important issues and pull requests that were integrated into the release.

The historic release announcements are still online here for various versions:

• 0.5,

• 1.0,

• 1.1,

• 1.2,

• 1.3,

• 1.4,

• 1.4.3,

• 1.8,

• 1.9,

• 2.0,

• 2.4.0.

Happy testing, The tox maintainers