tox uses pluggy to customize the default behaviour. It provides an extension mechanism for plugin management an calling hooks.
Pluggy discovers a plugin by looking up for entry-points named
tox, for example in a pyproject.toml:
[project.entry-points.tox] your_plugin = "your_plugin.hooks"
Therefore, to start using a plugin, you solely need to install it in the same environment tox is running in and it will
be discovered via the defined entry-point (in the example above, tox will load
A plugin is created by implementing extension points in the form of hooks. For example the following code snippet would
define a new
--magic command line interface flag the user can specify:
from tox.config.cli.parser import ToxParser from tox.plugin import impl @impl def tox_add_option(parser: ToxParser) -> None: parser.add_argument("--magic", action="store_true", help="magical flag")
You can define such hooks either in a package installed alongside tox or within a
toxfile.py found alongside your
tox configuration file (root of your project).
- tox.plugin.NAME = 'tox'#
the name of the tox hook
decorator to mark tox plugin hooks
Register new tox environment type. You can register:
run environment: by default this is a local subprocess backed virtualenv Python
packaging environment: by default this is a PEP-517 compliant local subprocess backed virtualenv Python
Add a command line argument. This is the first hook to be called, right after the logging setup and config source discovery.
- tox.plugin.spec.tox_add_core_config(core_conf, state)#
Called when the core configuration is built for a tox environment.
- tox.plugin.spec.tox_add_env_config(env_conf, state)#
Called when configuration is built for a tox environment.
Called before the commands set is executed.
- tox.plugin.spec.tox_after_run_commands(tox_env, exit_code, outcomes)#
Called after the commands set is executed.
- tox.plugin.spec.tox_on_install(tox_env, arguments, section, of_type)#
Called before executing an installation command.
Adoption of a plugin under tox-dev Github organization#
You’re free to host your plugin on your favorite platform, however the core tox development is happening on Github,
tox-dev org organization. We are happy to adopt tox plugins under the
tox-dev organization if:
we determine it’s trying to solve a valid use case and it’s not malicious (e.g. no plugin that deletes the users home directory),
it’s released on PyPI with at least 100 downloads per month (to ensure it’s a plugin used by people).
What’s in for you in this:
you get owner rights on the repository under the tox-dev organization,
exposure of your plugin under the core umbrella,
backup maintainers from other tox plugin development.
How to apply:
Migration from tox 3#
This section explains how the plugin interface changed between tox 3 and 4, and provides guidance for plugin developers on how to migrate.
With tox 4 the Python discovery is performed
tox.tox_env.python.virtual_env.api._get_python that delegates the job
virtualenv. Therefore first define a new virtualenv discovery mechanism and then set that by setting the
VIRTUALENV_DISCOVERY environment variable.
Register new packager types via