tox

tox
Name	tox
Developer	Python Packaging Authority
Initial release	2008
Programming language	Python
License	MIT License
Repository	https://github.com/tox-dev/tox

tox is a generic virtualenv management and test command line tool for Python projects. It automates testing across multiple Python interpreters, manages virtual environments, and orchestrates commands such as testing, building, and linting. Widely used in open source and enterprise projects, it integrates with continuous integration services and a variety of testing frameworks.

Introduction

tox provides a standardized configuration-driven approach to create isolated environments and run commands, commonly used alongside tools such as pytest, nose, unittest, tox.ini-driven projects, and packaging systems like setuptools and pip. It is maintained by contributors affiliated with the Python Packaging Authority and hosted on platforms such as GitHub and mirrors referenced by PyPI. Projects from organizations like Mozilla, Canonical, Red Hat, and universities often include tox in their CI matrices to validate compatibility with interpreters such as CPython, PyPy, and Jython.

Features

tox supports parallel and sequential environment orchestration, interpreter selection, dependency isolation, and environment reuse. It defines named testenvs that can invoke commands for tools like pytest, tox-travis, flake8, Black, and sphinx. Dependency management leverages integrations with pip, virtualenv, and the system Python interpreter discovery used by pyenv. Advanced features include factor-based environment names, environment inheritance, passenv whitelisting for variables like those used by Travis CI and GitHub Actions, and plugin hooks for extension.

Configuration

Configuration is provided via an ini-style file, commonly named tox.ini, with sections mapping to environments and global options. Keys include deps, commands, envlist, basepython, and setenv, which reference interpreters like python3.8 or pypy3 when present on the system. Per-environment configuration can import environment variables set by services such as CircleCI, Jenkins, and GitLab CI/CD. The file format echoes conventions from setuptools and pytest configuration and can be validated and linted using tools developed by the Python Packaging Authority community.

Usage

Typical usage involves creating a tox.ini, installing tox via pip, and running tox from a project root to execute testenvs. Commands often run test suites under pytest, style checks with flake8, and type checks with mypy. Developers use tox locally to reproduce CI matrices that run on platforms like Travis CI, GitHub Actions, Azure Pipelines, and CircleCI; maintainers of projects such as Django, pandas, and scikit-learn employ similar workflows. Options include -e to select environments, -r to recreate environments, and -p to parallelize execution on multi-core hosts.

Plugins and Extensions

A plugin architecture allows community-contributed extensions such as tox-venv, tox-conda, tox-gh-actions, and tox-travis. Plugins integrate with package ecosystems and tools maintained by organizations like Anaconda, Inc. and projects like conda-forge. Third-party plugins facilitate caching, artifact collection, reporting, and interoperability with linters and formatters like ruff and pre-commit. The plugin API is documented in repositories hosted on GitHub and coordinated through issue trackers and contribution guides maintained by the Python Packaging Authority.

Integration with CI/CD

tox is frequently invoked inside CI job steps for platforms such as GitHub Actions, GitLab CI/CD, Travis CI, CircleCI, Jenkins, and Azure DevOps. Configurations map tox environments to CI matrix axes to run across interpreters, operating systems like Ubuntu, macOS, and Windows Server, and dependency permutations. Integration patterns include using tox to produce test artifacts consumed by codecov and to coordinate deployment gates linked to systems like Ansible and Kubernetes for downstream workflows.

History and Development

Originating in 2008 among Python packaging tooling efforts, the project evolved through contributions from community members and organizations involved with pip, virtualenv, and setuptools. Stewardship moved to the Python Packaging Authority and an active maintainer team that publishes releases and changelogs on GitHub and package indices on PyPI. Major milestones include adding plugin support, factor-based environments, improved Windows compatibility, and performance optimizations for environment creation and dependency resolution influenced by advances in pip and virtualenv.

Security and Best Practices

Best practices recommend pinning dependencies and using constraints files produced by tools like pip-tools to ensure reproducible environments. Use of isolated build environments, careful handling of passenv, and restricting network access in CI environments mitigate supply-chain risks highlighted by incidents tracked by organizations such as OWASP and CISA. Projects often combine tox with signing and verification workflows, artifact provenance, and dependency scanning services offered by vendors like GitHub Advanced Security and Sonatype to reduce vulnerability exposure. Consider running tox inside ephemeral runners provided by GitHub Actions or GitLab to limit credential persistence.

Category:Python (programming language) tools