tox plugins

New in version 2.0.

With tox-2.0 a few aspects of tox running can be experimentally modified by writing hook functions. The list of of available hook function is to grow over time on a per-need basis.

writing a setuptools entrypoints plugin

If you have a module you could use the following rough to make it into a package which you can upload to the Python packaging index:

# content of
from setuptools import setup

if __name__ == "__main__":
        description='tox plugin decsription',
        license="MIT license",
        entry_points={'tox': ['MYPLUGIN = tox_MYPLUGIN']},

If installed, the entry_points part will make tox see and integrate your plugin during startup.

You can install the plugin for development (“in-place”) via:

pip install -e .

and later publish it via something like:

python sdist register upload

Writing hook implementations

A plugin module defines one or more hook implementation functions by decorating them with tox’s hookimpl marker:

from tox import hookimpl

def tox_addoption(parser):
    # add your own command line options

def tox_configure(config):
    # post process tox configuration after cmdline/ini file have
    # been parsed

If you put this into a module and make it pypi-installable with the tox entry point you’ll get your code executed as part of a tox run.

tox hook specifications and related API

Hook specifications for tox.


add command line options to the argparse-style parser object.


called after command line options have been parsed and the ini-file has been read. Please be aware that the config object layout may change as its API was not designed yet wrt to providing stability (it was an internal thing purely before tox-2.0).


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.


[experimental] perform arbitrary action after running tests for this venv.

This could be used to have per-venv test reporting of pass/fail status.


[experimental] 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)[source]

[experimental] perform creation action for this venv.

tox.hookspecs.tox_testenv_install_deps(venv, action)[source]

[experimental] perform install dependencies action for this venv.

class tox.config.Parser[source]

command line and ini-parser control object.

add_argument(*args, **kwargs)[source]

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)[source]

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 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[source]

Global Tox config object.

envconfigs = None

dictionary containing envname to envconfig mappings

option = None

option namespace containing all parsed command line options

class tox.config.TestenvConfig[source]

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 = None

global tox config object

envname = None

test environment name


path to python executable.

factors = None

set of factors


path to directory where scripts/binaries reside.


path to python/jython executable.


return sitepackagesdir of the virtualenv environment. (only available during execution, not parsing)


return sitepackagesdir of the virtualenv environment.

class tox.venv.VirtualEnv[source]
getcommandpath(name, venv=True, cwd=None)[source]

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 whitelisted to come from external.

test environment name.


Path to environment base dir.


return status string for updating actual venv to match configuration. if status string is empty, all is ok.

class tox.session.Session[source]

(unstable API). the session object that ties together configuration, reporting, venv creation, testing.

Returns:Path to the distribution
Return type:py.path.local

return a VirtualEnv controler object for the ‘name’ env.

installpkg(venv, path)[source]

Install package in the specified virtual environment.

:param tox.config.VenvConfig: Destination environment :param str path: Path to the distribution package. :return: True if package installed otherwise False. :rtype: bool