Command line driven CI frontend and development task automation tool

tox github

Its core role is to support the creation of isolated Python environments where different versions of Python interpreters and various dependency libraries can be installed to facilitate automated testing, packaging, continuous integration, and other things.

In short, tox is a command-line tool for managing test virtual environments. It has been around for years and is widely used by developers, for example, the famous cloud computing platform OpenStack has adopted it as one of the most basic testing tools.

1.What can tox do?

The breakdown of uses includes:

  • Create development environment

  • Run static code analysis and testing tools

  • Automated build packages

  • Run tests against tox-built packages

  • Check that the package installs smoothly with different Python versions/interpreters

  • Unified Continuous Integration (CI) and Command Line Based Testing

  • Create and deploy project documentation

  • Distribute the package to PyPI or any other platform

The official tox documentation lists more than 40 example usage scenarios, a detailed list of which can be found in:


2.tox How is it configured?

About its usage: use pip install tox to install, tox to run the full test environment, and tox -e envname to run the specified environment. There are also quite a few command line arguments, which are viewed via tox -h.

The behavior of tox is controlled by its configuration file, which currently supports 3 types of configuration files:

  1. pyproject.toml

  2. tox.ini

  3. setup.cfg

Taking the tox project's own tox.ini configuration as an example, you can see that it is configured like this(



Each [xxx] and the contents below it form a section, with blank lines separating each section.

Below [tox] are global configuration items, and the envlist field defines the environment in which tox will operate. Under [xxx] are the configuration items for the xxx virtual environment. [xxx:yyy] inherits the xxx configuration and gives higher priority to its own configuration items.

For each virtual environment, there are many configuration items available, such as description, basepython, deps, commands, and so on.

tox also supports variable substitution, and it provides some built-in base variables (global or for virtual environments): {toxinidir}, {homedir}, {envname}, {envdir}, etc.

In addition to basic variable substitution, it supports these advanced uses:

  • Takes the operating system environment variable: {env:KEY}, which is equivalent to os.environ['KEY']. This can be changed to: {env:KEY:DEFAULTVALUE}, which uses the default value if the environment variable is not fetched; {env:KEY:{env:DEFAULT_OF_KEY}}, which achieves an if-else fetching effect

  • Pass command line arguments: {posargs:DEFAULTS}, use DEFAULTS value when there is no command line argument. Usage: tox arg1 arg2 pass two arguments, or tox -- --opt1 arg1 pass "--opt1 arg1" as a whole.

  • Passing values between sections: {[sectionname]valuename}, content from different sections can be passed for use.

    Interactive console injection: {tty:ON_VALUE:OFF_VALUE}, the first value is used when the interactive shell console is on, otherwise the second one is used. pytest is an example of this when using "--pdb".

The brackets "{}" can be used not only as a variable substitution, but also as a value for the "or relation" judgment. Look directly at the following example:

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

The 2 sets of brackets in {py27,py36}-django{15,16} have 2 values each, and they can actually be combined into 4 environments: py27-django15, py27-django16, py36-django15, py36-django16.

For more information on what configuration items are available for tox, conditions of use, what they mean, advanced usage, etc., see the official documentation at


3.Plugging in tox

In addition to its powerful configurability, tox is also highly extensible, it is pluggable, and an extremely rich plugin ecosystem has been created around it.

Using pip search tox, you can see a large number of libraries starting with "tox-", which are all tox plug-in packages. There are many familiar names such as setuptools, pipenv, conda, travis, pytest, docker, and so on.


tox opens up a lot of API interfaces for others to develop custom plugins.


4.The workflow of tox

Next, see how tox works:


The main links in its workflow are:

  • Configuration: load configuration files (such as tox.ini), parse command line parameters, read system environment variables, etc.

  • Packaging: optional, for projects with files, you can generate its source distribution in this step

  • Create a virtual environment: use virtualenv by default to create a virtual environment and install the required dependencies according to the "deps" in the configuration, then execute the configured commands (commands)

  • report:Summarize the results of all virtual environments and list them


tox itself is a testing tool that tries to automate, standardize, and streamline Pytho testing. But unlike unittest and pytest, which are testing frameworks, it works beyond the code level and is a project-level tool. Therefore, it needs to be combined with these testing frameworks or handle multiple automation tasks (e.g. running pep8, measuring code coverage, generating documentation, etc.) in order to better leverage its value.

One of its features is the creation/management of virtual environments, but this is only a means to facilitate testing, so it falls short in some aspects compared to other tools that can manage virtual environments, such as Virtualenvwrapper, conda, pipenv, poetry.

tox also has strong configurability and rich plugin support, which gives it a lot of possibilities and freedom in its use. As a result, it is still in continuous use by many loyal developers, for example, the author of the series of articles I just translated is one of its maintainers.


Finally, it should be added that tox uses configuration files as drivers, but they are quite cumbersome, so someone developed a nox similar to tox that uses Python files to do the configuration. This project is also very popular and has attracted many projects like pipx, urllib3, Salt, etc. If you are interested in this project, please check out:

Related articles

Mplfinance draws beautiful financial K-line charts

Recently, we found that many of our partners have the need to draw K-line charts, and some of them even write their own code to draw charts without using third-party modules, which is actually a completely repetitive task.

Python invoke task automation tool

Invoke is a spin-off from the well-known remote deployment tool Fabric, and together with paramiko are the two most core foundational components of the Fabric.

alive-progress example

I don't know if you have ever had the experience that you have written a program and it takes a long time to run each time. While waiting for the program to run you press enter again and again to prevent the program from getting stuck.

python fire examples

Python Fire, which can generate command-line interfaces from any Python code,Simply call the Fire function in any Python program to automatically convert that program to a CLI.

Pytype Usage and Examples

Pytype checks and infers the type of Python code:Use lint to check pure Python code, flag common errors such as misspelled property names, incorrect function calls, and much more, and it can even span files.

Encrypting files with Python

In life, sometimes we need to encrypt some important files,Python provides easy-to-use cryptographic libraries such as hashlib, base64, etc.

Quickly test your Python code with Hypothesis

Testing is important no matter which programming language or framework you use. hypothesis is an advanced testing library for Python. It allows writing test cases with parameters, and then generating easy-to-understand test data that makes the test fail.

mplcyberpunk tutorials

Cyberpunk 2077" is a very popular single-player game ~ The game is set in the year 2077, a highly developed technology but chaotic and disorderly "cyberpunk" city. In this world, although the technology is highly developed, but the standard of living of

Heartrate: Real-time Visualization for Python Execution

Heartate - Track programs like a heart rate,Heartrate is a Python tool library that allows you to visualize the execution of Python programs in real time. Monitoring a running Python program is shown in the following figure.