Install & Compatibility
Where this runs
No compatibility data collected yet for this library.
Code
Verified usage
This quickstart sets up a basic Python project with a `pyproject.toml` file configured for `tox`. It defines two environments: `py` (to run pytest) and `lint` (to run ruff). After running this Python script, navigate to the directory where it created the `pyproject.toml` and `my_package` folder, then simply execute `tox` in your terminal. tox will automatically create isolated virtual environments, install dependencies, and run the specified commands.
import os
# Create a dummy project structure
os.makedirs('my_package/tests', exist_ok=True)
with open('my_package/main.py', 'w') as f:
f.write('def add(a, b):\n return a + b')
with open('my_package/tests/test_main.py', 'w') as f:
f.write('from my_package.main import add\n\ndef test_add():\n assert add(1, 2) == 3')
# Create pyproject.toml for tox configuration
with open('pyproject.toml', 'w') as f:
f.write('''
[project]
name = "my_package"
version = "0.1.0"
[tool.tox]
env_list = ["py", "lint"]
[tool.tox.env_run_base]
description = "Run the test suite with pytest"
deps = ["pytest>=8"]
commands = ["pytest {posargs:tests}"]
[tool.tox.env.lint]
description = "Run linters"
skip_install = true
deps = ["ruff"]
commands = ["ruff check {posargs:.}"]
''')
print("Project setup complete. Now run 'tox' in your terminal.")
tox --version
Debug
Known issues
breakingUpgrading from tox 3 to tox 4 involves significant breaking changes due to a ground-up rewrite. Key changes include the CLI command structure (e.g., `tox run -e` instead of `tox -e`), stricter INI parsing rules (e.g., `#` is always a comment, `pass_env` requires comma/newline separators), removal of `-U` in `deps`, and a completely new plugin API. Environment names matching new `tox 4` subcommands can also lead to ambiguity.fixConsult the 'Upgrading to tox v4' documentation for a comprehensive guide. Update CLI commands, adjust INI configuration files to new parsing rules (e.g., escape literal `#` with `\#`, use `,` for `pass_env`), and rewrite any custom plugins to the new API.
affects: 3.x to 4.x
gotchatox environments are often reused for performance. However, tox does not always detect changes in `setup.py` or `requirements.txt` files that define package dependencies. This can lead to stale virtual environments where tests run against outdated dependencies.fixAlways explicitly recreate environments by running `tox -r` or `tox run -r` when you suspect dependency changes, or when encountering unexpected test failures due to environment state.
affects: All versions
gotchaBy design, tox environments are isolated and do not inherit host system environment variables unless explicitly configured. This can cause commands to fail if they rely on external environment variables (e.g., API keys, build flags) that are not passed through.fixUse the `pass_env` setting in your `tox.ini` or `pyproject.toml` to explicitly list environment variables that should be passed from the host to the tox environment. Wildcards (`*`) can be used for patterns.
affects: All versions
gotchatox supports multiple configuration files (`pyproject.toml` (native TOML), `tox.toml`, `pyproject.toml` (legacy INI via `legacy_tox_ini`), `tox.ini`, `setup.cfg`) with a specific precedence order. Mixing configuration styles or placing core settings in environment-specific sections can lead to ignored or unexpected behavior. TOML is the recommended format for new projects as of tox 4, offering more robustness, but INI remains supported.fixConsistently use one configuration format (preferably native `pyproject.toml` for new projects). Always place core settings in the global `[tox]` section (INI) or `[tool.tox]` table (TOML), and environment-specific settings within their respective `[testenv]` or `[tool.tox.env.<name>]` sections. Use `tox config` or `tox run -v` to inspect the resolved configuration and identify misplaced keys.
affects: All versions, especially tox 4.x
gotchaWhen `pip` executes inside a tox environment, it may issue warnings regarding running as the 'root' user, which can lead to permission issues, or display notices about available `pip` updates. These are `pip` specific advisories and not directly indicative of a `tox` failure or misconfiguration.fixTo address 'root' warnings, ensure `tox` is run as a non-root user. If running in a container as root is unavoidable, be aware of potential permission conflicts. Pip update notices can be ignored if not critical, or suppressed by setting `PIP_DISABLE_PIP_VERSION_CHECK=1` in `pass_env` (e.g., `pass_env = PIP_DISABLE_PIP_VERSION_CHECK`). Updating pip within a tox env is generally not recommended as dependency versions should be fixed.
affects: All versions
gotchapip warns about running as the 'root' user, which can lead to permission issues and conflicts with system package managers. Additionally, pip provides notices about new available versions.fixTo address the 'root' user warning, always run pip within a virtual environment. If running in a container, ensure that applications are run as a non-root user. For pip update notices, consider updating pip by running `pip install --upgrade pip` (preferably within a virtual environment).
affects: All versions of pip, especially when run in containerized environments or as root.
Errors
Common errors & fixes
command not found: tox
The 'tox' executable is not in your system's PATH, typically because it wasn't installed globally or the virtual environment it was installed into isn't activated.
fixInstall tox using `pip install tox` in your global environment or a project-specific virtual environment, and ensure that virtual environment is activated if applicable.
ModuleNotFoundError: No module named 'pytest'
A Python package required by your tests or application is missing from the `deps` list in your `tox.ini` file for the specific `testenv` where the error occurs.
fixAdd the missing package to the `deps` list in the relevant `[[testenv]]` section of your `tox.ini`. For example: `deps = pytest`
ERROR: InterpreterNotFound: python3.9
The specified Python interpreter version (e.g., `python3.9`) is not installed on your system or is not discoverable in the system's PATH.
fixInstall the required Python version on your system. If it's installed but not found, ensure it's in your system's PATH, or configure `base_python = /path/to/python3.9` in the `[[testenv]]` section of `tox.ini`.
ERROR: ConfigError: The 'commands' key is required in section 'testenv:py39'.
Your `tox.ini` configuration is missing a mandatory key like `commands` within a `[[testenv]]` section, or there's a syntax error preventing tox from parsing the configuration correctly.
fixReview your `tox.ini` file, ensuring all required keys are present and correctly formatted according to tox v4 configuration (e.g., `commands = python -m pytest`).
ERROR: tox.ini file not found.
Tox was executed in a directory that does not contain a `tox.ini` or `pyproject.toml` file with tox configuration, or the file is named incorrectly.
fixRun `tox` from the root directory of your project where `tox.ini` is located, or specify the path to your config file using `tox -c path/to/tox.ini`.
Upgrade
Version history
4.51.0latest on PyPI · released Mar 27, 2026
Audit
Dependencies
pythonrequiredRequires Python 3.10 or later to run tox itself, though it can create environments for older Python versions.