NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
PyPI, #908 most downloaded on PyPI
tox is a generic virtualenv management and test command line tool
Latest stable
4.67.15
Last release 4 days ago
17 Nov 2026
Ships fairly regularly
a new release about every 1 weeks
Nearly every release is documented
notes for 60 of the last 60 stable releases
2 versions withdrawn
withdrawn after publishing
16 years old
344 releases · first in 2010
Drag across the ruler to compare, or tap a release to open it.
TOML env_list now accepts bare range dicts ({ prefix = "3.", start = 12, stop = 14 }) and bare labeled dicts ({ ecosystem = ["oci", "python"] }) as to
<a name="release-4-53-0-added"></a>
env_list now accepts bare range dicts ({ prefix = "3.", start = 12, stop = 14 }) and bare labeled dicts ({ ecosystem = ["oci", "python"] }) as top-level items, removing the { product = [...] } wrapper when there is only a single factor group by @gaborbernat. (#3923)<a name="release-4-53-0-fixed"></a>
product factor-group list now raises a clear error pointing at the un-nesting fix, instead of silently producing a malformed environment name by @gaborbernat. (#3923)TOML env_list now accepts bare range dicts ({ prefix = "3.", start = 12, stop = 14 }) and bare labeled dicts ({ ecosystem = ["oci", "python"] }) as top-level items, removing the { product = [...] } wrapper when there is only a single factor group - by gaborbernat. (3923)
Nesting a range or labeled dict inside a product factor-group list now raises a clear error pointing at the un-nesting fix, instead of silently producing a malformed environment name - by gaborbernat. (3923)
Your coding agent can read these notes before it upgrades. Set up the MCP server →
Changing a resolution-affecting environment variable via set_env (e.g. PIP_INDEX_URL) now invalidates the install cache and triggers a reinstall, rath
<a name="release-4-52-1-fixed"></a>
set_env (e.g. PIP_INDEX_URL) now invalidates the install cache and triggers a reinstall, rather than incorrectly reusing the cached environment by @gaborbernat. (#3917)normalize_isa from python-discovery for architecture factor matching, supporting aliases like i686 → x86 and aarch64 → arm64 by @rahuldevikar. (#3919)Changing a resolution-affecting environment variable via set_env (e.g. PIP_INDEX_URL) now invalidates the install cache and triggers a reinstall, rather than incorrectly reusing the cached environment - by gaborbernat. (3917)
Use normalize_isa from python-discovery for architecture factor matching, supporting aliases like i686 → x86 and aarch64 → arm64 - by rahuldevikar. (3919)
Add virtualenv-pep-723 runner that reads dependencies and Python version from PEP 723 inline script metadata — no need to duplicate them in tox config
<a name="release-4-52-0-added"></a>
virtualenv-pep-723 runner that reads dependencies and Python version from PEP 723 inline script metadata — no need to duplicate them in tox config by @gaborbernat. (#3897)\.) in -x/--override keys, allowing overrides to target environments with dots in their names such as py3.14 by @gaborbernat. (#3910)<a name="release-4-52-0-fixed"></a>
Add virtualenv-pep-723 runner that reads dependencies and Python version from PEP 723 inline script metadata — no need to duplicate them in tox config - by gaborbernat. (3897)
Support escaped dots (\.) in -x/--override keys, allowing overrides to target environments with dots in their names such as py3.14 - by gaborbernat. (3910)
Auto-generate the manpage from the CLI argparse parser at wheel build time, fixing broken section headers and documenting all commands and options - by gaborbernat. (3878)
Add base_python_file configuration option to read the base Python version from a file (e.g. .python-version), similar to GitHub Actions' python-versio
<a name="release-4-51-0-added"></a>
base_python_file configuration option to read the base Python version from a file (e.g. .python-version), similar to GitHub Actions' python-version-file by @rahuldevikar (#3894)<a name="release-4-51-0-fixed"></a>
arm64, x86_64) from overriding explicit architecture factors in environment names, fixing cross-architecture conflicts in multiline factor conditionals by @rahuldevikar. (#3903)tox-gh via the TOML format. Previously this was only possible with the INI format. by @Daverball (#3905)Add base_python_file configuration option to read the base Python version from a file (e.g. .python-version), similar to GitHub Actions' python-version-file - by rahuldevikar (3894)
Prevent implicit machine ISA (e.g. arm64, x86_64) from overriding explicit architecture factors in environment names, fixing cross-architecture conflicts in multiline factor conditionals - by rahuldevikar. (3903)
Nested environment list configuration values are now properly parsed, validated and expanded by the TOML parser. This allows you to use generative environment lists in tox-gh via the TOML format. Previously this was only possible with the INI format. - by Daverball (3905)
Use separate .pkg environments for free-threaded Python targets by including the t suffix in the wheel build environment name (e.g., .pkg-cpython314t)
<a name="release-4-50-3-fixed"></a>
.pkg environments for free-threaded Python targets by including the t suffix in the wheel build environment name (e.g., .pkg-cpython314t), preventing wheel tag mismatches when building for py314t by @gaborbernat. (#3314)Use separate .pkg environments for free-threaded Python targets by including the t suffix in the wheel build environment name (e.g., .pkg-cpython314t), preventing wheel tag mismatches when building for py314t - by gaborbernat. (3314)
Fix the sdist to include the missing docs/man/tox.1.rst file for building the manpage
<a name="release-4-50-2-fixed"></a>
docs/man/tox.1.rst file for building the manpage (#3889)Fix the sdist to include the missing docs/man/tox.1.rst file for building the manpage (3889)
Detect and suggest normalized environment names when users specify dotted Python versions (e.g., py3.10-lint) that match existing environments with co
<a name="release-4-50-1-fixed"></a>
py3.10-lint) that match existing environments with compact notation (e.g., py310-lint), preventing silent fallback to base [testenv] configuration by @gaborbernat. (#3877)Detect and suggest normalized environment names when users specify dotted Python versions (e.g., py3.10-lint) that match existing environments with compact notation (e.g., py310-lint), preventing silent fallback to base [testenv] configuration - by gaborbernat. (3877)
Add interrupt_post_commands option to run cleanup commands even after SIGINT by @gaborbernat.
<a name="release-4-50-0-added"></a>
interrupt_post_commands option to run cleanup commands even after SIGINT by @gaborbernat. (#3858)factor['NAME'] and env['VAR'] subscript syntax for conditional expressions, enabling checks of factors with non-identifier names like factor['3.14']. Add env_name variable to check the full environment name in conditions. (#3880)<a name="release-4-50-0-fixed"></a>
project in Sphinx config, and compile the manpage to troff format at wheel-build time instead of shipping raw RST source by @gaborbernat. (#3878)<a name="release-4-50-0-documentation"></a>
TOX_PACKAGE by @rahuldevikar (#3862)extend = true on conditional replacements inside lists, fix incorrect ref of path in raw reference docs, and add a test that validates all doc config examples by @gaborbernat (#3875)Add interrupt_post_commands option to run cleanup commands even after SIGINT - by gaborbernat. (3858)
Add factor['NAME'] and env['VAR'] subscript syntax for conditional expressions, enabling checks of factors with non-identifier names like factor['3.14']. Add env_name variable to check the full environment name in conditions. (3880)
Fix multiple manpage issues: remove duplicate header/author/copyright sections, set project in Sphinx config, and compile the manpage to troff format at wheel-build time instead of shipping raw RST source - by gaborbernat. (3878)
Document how to reference the built package path in commands via TOX_PACKAGE - by rahuldevikar (3862)
Fix broken TOML examples missing extend = true on conditional replacements inside lists, fix incorrect ref of path in raw reference docs, and add a test that validates all doc config examples - by gaborbernat (3875)
Break deadlock in execution interrupt chain that caused \~18 flaky timeout failures across 9 tests on Windows/macOS CI by @gaborbernat.
<a name="release-4-49-1-fixed"></a>
Break deadlock in execution interrupt chain that caused ~18 flaky timeout failures across 9 tests on Windows/macOS CI by gaborbernat. (3869)
Add {factor:label} substitution for TOML configs -- factor groups in product matrices and env_base factors can now be labeled with single-key dicts (e
<a name="release-4-49-0-added"></a>
{factor:label} substitution for TOML configs -- factor groups in product matrices and env_base factors can now be labeled with single-key dicts (e.g., {ecosystem = ["oci", "python"]}), enabling {factor:ecosystem} in any string value (descriptions, commands, etc.) to resolve to the active factor. Plain lists automatically get positional labels ({factor:0}, {factor:1}, ...) by @gaborbernat. (#3860) (#3860)<a name="release-4-49-0-fixed"></a>
--showconfig and --help-ini legacy flags raising AttributeError after config format options were added by @rares985 (#3866)Add {factor:label} substitution for TOML configs -- factor groups in product matrices and env_base factors can now be labeled with single-key dicts (e.g., {ecosystem = ["oci", "python"]}), enabling {factor:ecosystem} in any string value (descriptions, commands, etc.) to resolve to the active factor. Plain lists automatically get positional labels ({factor:0}, {factor:1}, ...) - by gaborbernat. (3860) (3860)
Fix --showconfig and --help-ini legacy flags raising AttributeError after config format options were added by rares985 (3866)
Command-type configuration values like list_dependencies_command can now be referenced in TOML using the structured {replace = "ref"} syntax. The refe
<a name="release-4-48-1-fixed"></a>
list_dependencies_command can now be referenced in TOML using the structured {replace = "ref"} syntax. The reference automatically extracts the command's argument list for compatibility with TOML's list[list[str]] structure by @gaborbernat. (#3830)<a name="release-4-48-1-documentation"></a>
31z4/tox Docker image recommendation with instructions for building your own image using the official Python base image and uv by @rahuldevikar. (#3855)Command-type configuration values like list_dependencies_command can now be referenced in TOML using the structured {replace = "ref"} syntax. The reference automatically extracts the command's argument list for compatibility with TOML's list[list[str]] structure - by gaborbernat. (3830)
Replace archived 31z4/tox Docker image recommendation with instructions for building your own image using the official Python base image and uv - by rahuldevikar. (3855)
Add --format flag (ini, json, toml) and -o/--output-file to the config command for machine-readable output with native types. JSON and TOML use the sa
<a name="release-4-48-0-added"></a>
--format flag (ini, json, toml) and -o/--output-file to the config command for machine-readable output with native types. JSON and TOML use the same key structure as tox.toml (env.<name> for environments, tox for core) and get syntax-highlighted on stdout by @gaborbernat. (#3854)<a name="release-4-48-0-documentation"></a>
fail_fast to the configuration reference documentation by @rahuldevikar. (#578)Add --format flag (ini, json, toml) and -o/--output-file to the config command for machine-readable output with native types. JSON and TOML use the same key structure as tox.toml (env.<name> for environments, tox for core) and get syntax-highlighted on stdout - by gaborbernat. (3854)
Add fail_fast to the configuration reference documentation - by rahuldevikar. (578)
ignore_base_python_conflict now also suppresses errors when an environment name contains multiple conflicting version-like factors (e.g., unit-py3.10-
<a name="release-4-47-3-fixed"></a>
ignore_base_python_conflict now also suppresses errors when an environment name contains multiple conflicting version-like factors (e.g., unit-py3.10-2.16 where both py3.10 and 2.16 are detected as Python versions). Previously this flag only handled conflicts between explicit base_python settings and the environment name by @gaborbernat. (#3850)ignore_base_python_conflict now also suppresses errors when an environment name contains multiple conflicting version-like factors (e.g., unit-py3.10-2.16 where both py3.10 and 2.16 are detected as Python versions). Previously this flag only handled conflicts between explicit base_python settings and the environment name - by gaborbernat. (3850)
Handle OSError when checking if positional arguments are existing paths in pos_args() — long arguments (e.g., pytest -k expressions exceeding the 255-
<a name="release-4-47-2-fixed"></a>
OSError when checking if positional arguments are existing paths in pos_args() — long arguments (e.g., pytest -k expressions exceeding the 255-character filesystem name limit) no longer crash with OSError: [Errno 36] File name too long by @yarikoptic. (#3847)Handle OSError when checking if positional arguments are existing paths in pos_args() — long arguments (e.g., pytest -k expressions exceeding the 255-character filesystem name limit) no longer crash with OSError: [Errno 36] File name too long - by yarikoptic. (3847)
New-style version factors (e.g., 3.10-tests) now correctly set base_python by @gaborbernat.
<a name="release-4-47-1-fixed"></a>
3.10-tests) now correctly set base_python by @gaborbernat. (#3845)New-style version factors (e.g., 3.10-tests) now correctly set base_python - by gaborbernat. (3845)
Show clean error messages instead of stack traces when TOML configuration contains type mismatches (e.g., deps = [1]), wrapping failures in HandledErr
<a name="release-4-47-0-added"></a>
deps = [1]), wrapping failures in HandledError with environment and key context by @gaborbernat. (#3831)<a name="release-4-47-0-fixed"></a>
ty for virtualenv API changes (system_executable nullability and cached_py_info.PythonInfo removal), and correct the CI workflow matrix exclude for windows-2025 by @gaborbernat. (#3837)base_python and default_base_python now accept a string value in TOML configuration (e.g., base_python = "python" is coerced to ["python"]) instead of raising TypeError by @gaborbernat. (#3839)tox exec so that piped input (e.g., echo "foo" | tox exec -- python -c 'import sys; print(sys.stdin.read())') reaches the subprocess instead of being discarded by @gaborbernat. (#3841)Show clean error messages instead of stack traces when TOML configuration contains type mismatches (e.g., deps = [1]), wrapping failures in HandledError with environment and key context - by gaborbernat. (3831)
Add comprehensive tests asserting full error messages for every configurable field type when TOML config contains type mismatches - by gaborbernat. (3840)
Fix type errors flagged by ty for virtualenv API changes (system_executable nullability and cached_py_info.PythonInfo removal), and correct the CI workflow matrix exclude for windows-2025 - by gaborbernat. (3837)
base_python and default_base_python now accept a string value in TOML configuration (e.g., base_python = "python" is coerced to ["python"]) instead of raising TypeError - by gaborbernat. (3839)
Pass stdin through to commands executed via tox exec so that piped input (e.g., echo "foo" | tox exec -- python -c 'import sys; print(sys.stdin.read())') reaches the subprocess instead of being discarded - by gaborbernat. (3841)
Fix SchemaStore update workflow creating PRs with merge conflicts by branching from upstream master by @gaborbernat.
<a name="release-4-46-3-fixed"></a>
Fix SchemaStore update workflow creating PRs with merge conflicts by branching from upstream master - by gaborbernat. (3828)
Fixed the minimum version of virtualenv, to avoid incompatibility. (3829)
Fix SchemaStore update workflow authentication and PR creation for fork repositories by @gaborbernat.
<a name="release-4-46-2-fixed"></a>
Fix SchemaStore update workflow authentication and PR creation for fork repositories - by gaborbernat. (3826)
Allow glob patterns (*, ?) in depends configuration for ini files by @gaborbernat.
<a name="release-4-46-1-fixed"></a>
*, ?) in depends configuration for ini files by @gaborbernat. (#3822)additionalProperties: true to partial-tox.json on SchemaStore by @gaborbernat. (#3823)Allow glob patterns (*, ?) in depends configuration for ini files - by gaborbernat. (3822)
Fix false positive schema validation errors with tombi by adding additionalProperties: true to partial-tox.json on SchemaStore - by gaborbernat. (3823)
Add architecture (ISA) awareness to Python discovery. tox now propagates the machine field (e.g. arm64, x86_64) from virtualenv's interpreter info — d
<a name="release-4-46-0-added"></a>
machine field (e.g. arm64, x86_64) from virtualenv's interpreter info — derived from get_platform — through the Python specification, validation, and journal. This allows selecting a Python interpreter by CPU architecture via base_python (e.g. cpython3.12-64-arm64) and ensures tox validates the running interpreter's architecture matches the requested one. Requires virtualenv >= 20.39 by @rahuldevikar. (#3069)env_base TOML sections for named environment templates that generate multiple environments from factor combinations via Cartesian product -- by @gaborbernat. (#3817)<a name="release-4-46-0-fixed"></a>
chardet dependency and use BOM detection with locale fallback for requirements file decoding, matching pip's own approach by @gaborbernat. (#3818)--help to render even when the configuration file is malformed or missing by @gaborbernat. (#3819)Add architecture (ISA) awareness to Python discovery. tox now propagates the machine field (e.g. arm64, x86_64) from virtualenv's interpreter info — derived from python:sysconfig.get_platform — through the Python specification, validation, and journal. This allows selecting a Python interpreter by CPU architecture via base_python (e.g. cpython3.12-64-arm64) and ensures tox validates the running interpreter's architecture matches the requested one. Requires virtualenv >= 20.39 - by rahuldevikar. (3069)
Add env_base TOML sections for named environment templates that generate multiple environments from factor combinations via Cartesian product -- by gaborbernat. (3817)
Drop chardet dependency and use BOM detection with locale fallback for requirements file decoding, matching pip's own approach - by gaborbernat. (3818)
Allow --help to render even when the configuration file is malformed or missing - by gaborbernat. (3819)
Enhance tox schema command: add x-taplo metadata for IDE integration, product dict support for env_list, handle int and PythonConstraints types, fix $
<a name="release-4-45-0-added"></a>
tox schema command: add x-taplo metadata for IDE integration, product dict support for env_list, handle int and PythonConstraints types, fix $schema draft-07 URI, and add schema freshness test. Add tox.toml to SchemaStore catalog for automatic IDE validation by @gaborbernat. (#1388)<a name="release-4-45-0-fixed"></a>
/config.html -> /reference/config.html, /example/general.html -> /index.html) using sphinx-reredirects by @gaborbernat. (#3806){[section]key} resolving to a literal unresolved reference instead of empty string when the referenced value contains only factor-conditional lines and no factors match the requesting environment by @Fridayai700. (#3809)environment_variables when set_env references {env_site_packages_dir} or similar lazy constants, causing RecursionError silently caught as "could not find python interpreter" by @gaborbernat. (#3816)Enhance tox schema command: add x-taplo metadata for IDE integration, product dict support for env_list, handle int and PythonConstraints types, fix $schema draft-07 URI, and add schema freshness test. Add tox.toml to SchemaStore catalog for automatic IDE validation - by gaborbernat. (1388)
Add redirects for old documentation URLs that broke after the Diataxis restructure (e.g. /config.html -> /reference/config.html, /example/general.html -> /index.html) using sphinx-reredirects - by gaborbernat. (3806)
Fix cross-section substitution {[section]key} resolving to a literal unresolved reference instead of empty string when the referenced value contains only factor-conditional lines and no factors match the requesting environment - by Fridayai700. (3809)
Fix circular dependency in environment_variables when set_env references {env_site_packages_dir} or similar lazy constants, causing RecursionError silently caught as "could not find python interpreter" - by gaborbernat. (3816)
Support PEP 751 pylock.toml lock files as dependency input via the pylock configuration option (mutually exclusive with deps). Packages are filtered b
<a name="release-4-44-0-added"></a>
pylock.toml lock files as dependency input via the pylock configuration option (mutually exclusive with deps). Packages are filtered by extras, dependency groups, and platform markers evaluated against the target Python interpreter, then installed via pip with --no-deps by @gaborbernat. (#3665)<a name="release-4-44-0-fixed"></a>
pytest \, --remote-data \) being incorrectly skipped when they follow a filtered factor-conditional line ending with \ -- the pending_skip flag now only drops terminal continuation pieces, preserving shared arguments that are themselves continuations by @gaborbernat. (#3802)Support PEP 751 pylock.toml lock files as dependency input via the pylock configuration option (mutually exclusive with deps). Packages are filtered by extras, dependency groups, and platform markers evaluated against the target Python interpreter, then installed via pip with --no-deps - by gaborbernat. (3665)
Fix unfactored continuation lines (e.g. pytest \, --remote-data \) being incorrectly skipped when they follow a filtered factor-conditional line ending with \ -- the pending_skip flag now only drops terminal continuation pieces, preserving shared arguments that are themselves continuations - by gaborbernat. (3802)
Add TOML-native generative env_list via product dict syntax -- Cartesian product of factor groups with optional range dicts and exclusions by @gaborbe
<a name="release-4-43-0-added"></a>
env_list via product dict syntax -- Cartesian product of factor groups with optional range dicts and exclusions by @gaborbernat. (#3797)<a name="release-4-43-0-fixed"></a>
config_settings_build_wheel to pip as --config-settings when installing sdist packages, ensuring the build backend receives config settings during pip's internal wheel build by @gaborbernat. (#3125)cov: coverage run \ / !cov: python \ / somefile.py) where different factor prefixes on consecutive continuation lines caused prefixes to be passed as literal command arguments instead of being filtered by @gaborbernat. (#3796)<a name="release-4-43-0-documentation"></a>
sphinxcontrib-towncrier to render draft changelog entries directly in Sphinx, replacing the manual towncrier draft script by @gaborbernat. (#3201)Add TOML-native generative env_list via product dict syntax -- Cartesian product of factor groups with optional range dicts and exclusions - by gaborbernat. (3797)
Pass config_settings_build_wheel to pip as --config-settings when installing sdist packages, ensuring the build backend receives config settings during pip's internal wheel build - by gaborbernat. (3125)
Fix factor-conditional continuation lines (e.g. cov: coverage run \ / !cov: python \ / somefile.py) where different factor prefixes on consecutive continuation lines caused prefixes to be passed as literal command arguments instead of being filtered - by gaborbernat. (3796)
Integrate sphinxcontrib-towncrier to render draft changelog entries directly in Sphinx, replacing the manual towncrier draft script - by gaborbernat. (3201)
Improve towncrier changelog structure with more granular categories: breaking, deprecation, feature, bugfix, doc, packaging, contrib, and misc by @gab…
<a name="release-4-42-0-added"></a>
sys.platform value like linux, darwin, win32) is automatically available as an implicit factor, allowing configurations like linux: pytest in INI or factor.linux in TOML conditional expressions to work in any environment. Additionally, TOML configurations can now use factor.NAME in conditional expressions to filter settings based on environment name factors, achieving feature parity with INI's factor system by @gaborbernat. (#2092){env_site_packages_dir_plat} / {envsitepackagesdir_plat} substitution that returns the platform-specific (platlib) site-packages directory. On some Linux distributions (Fedora, RHEL) this resolves to lib64 instead of lib, which is no longer symlinked since virtualenv 20.x by @gaborbernat. (#2302)package = external) now only run their build commands once per session, reusing the built package for all test environments that depend on them by @gaborbernat. (#2729)default_base_python configuration key to specify a fallback Python interpreter when no Python factor or explicit base_python is defined. This allows projects to pin a default Python version for reproducibility across different machines without conflicting with pyXY factor-named environments by @gaborbernat. (#2846)requires are now accepted during provisioning instead of failing with "unrecognized arguments" by @gaborbernat. (#2935)tox run -v by @gaborbernat. (#3188)breaking, deprecation, feature, bugfix, doc, packaging, contrib, and misc by @gaborbernat. (#3200)--skip-env-install CLI flag to skip dependency and package installation, allowing reuse of existing environments when offline or when installation is unnecessary by @gaborbernat. (#3310)recreate_commands configuration option to run cleanup commands (e.g. clearing external caches like pre-commit) before the environment directory is removed during recreation (-r) by @gaborbernat. (#3423)-e, a clear error message is shown indicating which runner is missing and that the plugin may not be installed. Unavailable environments in the configuration don't cause the overall run to fail by @gaborbernat. (#3504)py3{9-} expands up to the latest supported CPython minor version and py3{-13} expands down to the oldest supported one, both hardcoded at release time per the Python release cycle by @gaborbernat. (#3583)--no-capture (-i) CLI flag to disable output capture, allowing interactive programs like Python REPL to access the terminal directly. When enabled, subprocess inherits parent console handles instead of pipes, fixing issues where terminal APIs (e.g., querying console dimensions) fail on pipe handles. Mutually exclusive with --result-json and parallel mode by @gaborjbernat. Fixes #3635. (#3635)virtualenv_spec configuration key that allows pinning a specific virtualenv version per environment (e.g. virtualenv_spec = "virtualenv<20.22.0"). When set, tox bootstraps the specified version in an isolated environment and drives it via subprocess, enabling environments targeting Python versions incompatible with the installed virtualenv by @gaborbernat. (#3656)<a name="release-4-42-0-fixed"></a>
BrokenPipeError during backend teardown when interrupted, preventing traceback spam during KeyboardInterrupt by @gaborjbernat. Fixes #2660. (#2660)\) no longer leak continuation lines into environments that don't match the factor by @gaborbernat. (#2912)--list-dependencies output is now printed to stdout during parallel runs. Previously, the dependency list was captured in suspended output buffers and only shown on failure by @gaborbernat. (#3322)np-cov: coverage) now correctly allow their individual factors to be used when specifying environments with -e. Previously, running tox -e py310-np-cov with a factor conditional np-cov: coverage in the config would fail with "provided environments not found" because the individual factor cov was not recognized as combinable by @gaborbernat. (#3780)<a name="release-4-42-0-documentation"></a>
python3-venv limitation in known limitations by @gaborbernat. (#3195)Platform-dependent commands can now be specified using factor syntax without requiring the platform name in the environment name. The current platform (sys.platform value like linux, darwin, win32) is automatically available as an implicit factor, allowing configurations like linux: pytest in INI or factor.linux in TOML conditional expressions to work in any environment. Additionally, TOML configurations can now use factor.NAME in conditional expressions to filter settings based on environment name factors, achieving feature parity with INI's factor system - by gaborbernat. (2092)
Add {env_site_packages_dir_plat} / {envsitepackagesdir_plat} substitution that returns the platform-specific (platlib) site-packages directory. On some Linux distributions (Fedora, RHEL) this resolves to lib64 instead of lib, which is no longer symlinked since virtualenv 20.x - by gaborbernat. (2302)
External packaging environments (package = external) now only run their build commands once per session, reusing the built package for all test environments that depend on them - by gaborbernat. (2729)
Add default_base_python configuration key to specify a fallback Python interpreter when no Python factor or explicit base_python is defined. This allows projects to pin a default Python version for reproducibility across different machines without conflicting with pyXY factor-named environments - by gaborbernat. (2846)
CLI options added by plugins listed in requires are now accepted during provisioning instead of failing with "unrecognized arguments" - by gaborbernat. (2935)
Warn about unused configuration keys during tox run -v - by gaborbernat. (3188)
Improve towncrier changelog structure with more granular categories: breaking, deprecation, feature, bugfix, doc, packaging, contrib, and misc - by gaborbernat. (3200)
Add --skip-env-install CLI flag to skip dependency and package installation, allowing reuse of existing environments when offline or when installation is unnecessary - by gaborbernat. (3310)
Add recreate_commands configuration option to run cleanup commands (e.g. clearing external caches like pre-commit) before the environment directory is removed during recreation (-r) - by gaborbernat. (3423)
Environments with unavailable runners (missing plugins) are now gracefully skipped instead of causing a fatal error, shown with status "NOT AVAILABLE". If such an environment is explicitly requested with -e, a clear error message is shown indicating which runner is missing and that the plugin may not be installed. Unavailable environments in the configuration don't cause the overall run to fail - by gaborbernat. (3504)
Add open-ended range expansion in generative env lists — py3{9-} expands up to the latest supported CPython minor version and py3{-13} expands down to the oldest supported one, both hardcoded at release time per the Python release cycle - by gaborbernat. (3583)
Add --no-capture (-i) CLI flag to disable output capture, allowing interactive programs like Python REPL to access the terminal directly. When enabled, subprocess inherits parent console handles instead of pipes, fixing issues where terminal APIs (e.g., querying console dimensions) fail on pipe handles. Mutually exclusive with --result-json and parallel mode - by gaborjbernat. Fixes 3635. (3635)
Add virtualenv_spec configuration key that allows pinning a specific virtualenv version per environment (e.g. virtualenv_spec = "virtualenv<20.22.0"). When set, tox bootstraps the specified version in an isolated environment and drives it via subprocess, enabling environments targeting Python versions incompatible with the installed virtualenv - by gaborbernat. (3656)
Suppress BrokenPipeError during backend teardown when interrupted, preventing traceback spam during KeyboardInterrupt - by gaborjbernat. Fixes 2660. (2660)
Factor-specific multiline commands using backslash continuation (\) no longer leak continuation lines into environments that don't match the factor - by gaborbernat. (2912)
--list-dependencies output is now printed to stdout during parallel runs. Previously, the dependency list was captured in suspended output buffers and only shown on failure - by gaborbernat. (3322)
Compound factor conditionals (e.g., np-cov: coverage) now correctly allow their individual factors to be used when specifying environments with -e. Previously, running tox -e py310-np-cov with a factor conditional np-cov: coverage in the config would fail with "provided environments not found" because the individual factor cov was not recognized as combinable - by gaborbernat. (3780)
Document Debian/Ubuntu python3-venv limitation in known limitations - by gaborbernat. (3195)
Add package = "deps-only" mode that installs the package's dependencies (including extras) without building or installing the package itself. For proj
<a name="release-4-41-0-added"></a>
package = "deps-only" mode that installs the package's dependencies (including extras) without building or installing the package itself. For projects with static PEP 621 metadata, dependencies are read directly from pyproject.toml without creating a packaging environment by @gaborbernat. (#2301)[tool.tox]) over legacy_tox_ini when both are present in pyproject.toml, allowing users to include a legacy_tox_ini section with min_version for older tox versions while using native TOML config for newer ones by @rahuldevikar. (#3402)<a name="release-4-41-0-fixed"></a>
ENOENT (missing interpreter) and runtime crashes without hanging, and fix flaky test_provision_install_pkg_pep517 integration test by using a pre-built wheel instead of an sdist to avoid devpi mirror dependency on setuptools by @gaborjbernat. (#3774)Add package = "deps-only" mode that installs the package's dependencies (including extras) without building or installing the package itself. For projects with static PEP 621 metadata, dependencies are read directly from pyproject.toml without creating a packaging environment - by gaborbernat. (2301)
Prefer TOML-native configuration ([tool.tox]) over legacy_tox_ini when both are present in pyproject.toml, allowing users to include a legacy_tox_ini section with min_version for older tox versions while using native TOML config for newer ones - by rahuldevikar. (3402)
Fix PEP 517 backend crash detection to handle both ENOENT (missing interpreter) and runtime crashes without hanging, and fix flaky test_provision_install_pkg_pep517 integration test by using a pre-built wheel instead of an sdist to avoid devpi mirror dependency on setuptools - by gaborjbernat. (3774)
Add {glob:PATTERN} substitution to expand file system glob/wildcard patterns in configuration values. Supports default values, recursive matching, and
<a name="release-4-40-0-added"></a>
{glob:PATTERN} substitution to expand file system glob/wildcard patterns in configuration values. Supports default values, recursive ** matching, and both INI string syntax and TOML dict syntax ({ replace = "glob", pattern = "..." }) by @gaborbernat. (#1571)commands_retry configuration option to automatically retry failed commands by @gaborbernat. (#1578).gitignore file containing * in the tox work directory (typically .tox/) and in environment info directories, so that tox-managed files are not tracked by git by @rahuldevikar. (#2530)replace = "if" in TOML configuration. Supports a condition expression with env.VAR lookups, ==/!= comparisons, and and/or/not boolean logic to select between then and else values by @gaborbernat. (#3650)sdist-wheel package type that builds a wheel from a source distribution, ensuring the sdist is complete and the package can be correctly built from it — by @rahuldevikar. (#3687)<a name="release-4-40-0-fixed"></a>
1) instead of -1 when reporting failures across multiple environments. On Windows, cmd.exe's IF ERRORLEVEL 1 only matches exit codes >= 1, so the previous negative exit code was silently treated as success by @radevika. Fixes #2945. (#2945)set_env both inherits via cross-section substitution (e.g., {[testenv]set_env}) and explicitly overrides the same variable, the explicit value was incorrectly replaced by the inherited one because load() moved the key from the raw dict to the materialized dict before the deferred substitution ran, making the protection check ineffective by @gaborjbernat. Fixes #3773. (#3773)Add {glob:PATTERN} substitution to expand file system glob/wildcard patterns in configuration values. Supports default values, recursive ** matching, and both INI string syntax and TOML dict syntax ({ replace = "glob", pattern = "..." }) - by gaborbernat. (1571)
Add commands_retry configuration option to automatically retry failed commands - by gaborbernat. (1578)
Automatically create a .gitignore file containing * in the tox work directory (typically .tox/) and in environment info directories, so that tox-managed files are not tracked by git - by rahuldevikar. (2530)
Add conditional value selection via replace = "if" in TOML configuration. Supports a condition expression with env.VAR lookups, ==/!= comparisons, and and/or/not boolean logic to select between then and else values - by gaborbernat. (3650)
Add sdist-wheel package type that builds a wheel from a source distribution, ensuring the sdist is complete and the package can be correctly built from it — by rahuldevikar. (3687)
Use positive exit code (1) instead of -1 when reporting failures across multiple environments. On Windows, cmd.exe's IF ERRORLEVEL 1 only matches exit codes >= 1, so the previous negative exit code was silently treated as success - by radevika. Fixes 2945. (2945)
When set_env both inherits via cross-section substitution (e.g., {[testenv]set_env}) and explicitly overrides the same variable, the explicit value was incorrectly replaced by the inherited one because load() moved the key from the raw dict to the materialized dict before the deferred substitution ran, making the protection check ineffective - by gaborjbernat. Fixes 3773. (3773)
Fix pytest INTERNALERROR on Python 3.15 caused by Pygments using deprecated os.path.commonprefix() by @gaborbernat.
<a name="release-4-39-0-added"></a>
CACHEDIR.TAG file in the tox work directory (.tox) so that backup and archiving tools (e.g., tar --exclude-caches, Borg, restic) can automatically skip it by @radevika. (#3334)<a name="release-4-39-0-fixed"></a>
.tox) -- a file lock now serializes provisioning across processes by @gaborbernat. (#2515)tox.ini, setup.cfg) with unicode characters are now read correctly on Windows when running tox with python -m -I (isolation mode) by @gaborbernat. (#2692)set_env values explicitly defined in a section now take precedence over values inherited via cross-section substitution (e.g., {[testenv]set_env}) by @gaborbernat. (#2831)-e flag now supports brace expansion (e.g. tox -e 'py{38,39}-pytest{6.x,7.x}') instead of incorrectly splitting on commas inside braces by @gaborbernat. (#2850){posargs} in path-like configuration values such as env_dir by @gaborbernat. (#2860)set_env values from cross-section substitution (e.g., {[testenv]set_env}) now correctly override default environment variables like PYTHONHASHSEED by @gaborbernat. (#2872)--force-dep now applies to package dependencies from project metadata (e.g. setup.cfg install_requires, pyproject.toml dependencies), not just tox config deps by @gaborbernat. (#2943){posargs} in change_dir no longer causes a RecursionError by @gaborbernat. (#3062){[testenv:a]commands}) now resolves environment-specific variables like {envpython}, {envbindir}, {envtmpdir}, and {envsitepackagesdir} in the calling environment's context rather than the referenced environment's context by @gaborbernat. (#3075)ValueError crash when using posargs on Windows with subst drive mappings -- os.path.relpath fails across drive letters, so fall back to absolute paths when the relative path cannot be computed by @gaborbernat. (#3086)TOX_OVERRIDE with += (append) now works correctly when the override key name differs from the config file key name (e.g., overriding pass_env when config uses passenv, or vice versa) by @gaborbernat. (#3127)setup.cfg -- packages = find: in [options] was incorrectly interpreted as a tox factor marker, creating a phantom find environment by @gaborbernat. (#3134)requires with environment markers that evaluate to false (e.g. virtualenv<20.22.0; python_version < "3.8") are now correctly skipped during provisioning instead of causing an infinite provisioning loop by @gaborbernat. (#3136)recreate = true no longer destroys shared package environments (e.g. .pkg), which previously caused FileNotFoundError when a subsequent environment tried to use the already-built wheel by @gaborbernat. (#3146)base_python = py312: python3.12) now correctly fall back to the default when no factors match the current environment, instead of producing an empty value by @gaborbernat. (#3189)TOX_PARALLEL_NO_SPINNER / --parallel-no-spinner no longer forces parallel mode in the legacy command, fixing output suppression for sequential runs in CI by @gaborbernat. (#3193)-e flags are now additive (tox r -e a -e b runs both a and b), matching tox 3 behavior by @gaborbernat. (#3199)functional-py312 no longer incorrectly match when only functional{-py310} is defined as a testenv section -- factors from section headers are no longer treated as freely combinable with CLI -e selections by @gaborbernat. (#3219){/}) no longer causes the next command argument to be merged into the path - backslash before whitespace is now treated as a literal path separator rather than a space escape by @gaborbernat. (#3222){envtmpdir} and other env variable substitutions not expanding in external package environment commands by @gaborbernat. (#3238) (#3238)--colored yes flag to the provisioned subprocess when the parent has colors enabled by @gaborbernat. (#3331)set_env values defined after a file| reference now correctly take precedence over values loaded from the env file by @gaborbernat. (#3335)base configuration key now works correctly in TOML format (tox.toml and pyproject.toml), allowing environments to inherit from arbitrary sections defined under [env.*] by @gaborbernat. (#3497)toxfile.py inline plugin when it uses hooks not available in the current tox version instead of crashing - this allows provisioning to upgrade tox to a version that supports those hooks by @gaborbernat. (#3593)set_env substitution referencing {envsitepackagesdir}, {envbindir}, or {envpython} for environments with missing interpreters now raises Skip instead of RuntimeError, allowing skip_missing_interpreters to work correctly by @gaborbernat. (#3597)setup.cfg without a [tox:tox] section no longer blocks discovery of pyproject.toml or tox.toml configuration files in the same directory by @gaborbernat. (#3602)INTERNALERROR on Python 3.15 caused by Pygments using deprecated os.path.commonprefix() by @gaborbernat. (#3733)RecursionError when TOML set_env contains substitutions like {env_site_packages_dir} that trigger config loading cycles -- the TOML loader now defers string substitution in set_env values, matching the INI loader's lazy resolution behavior by @gaborbernat. (#3758)<a name="release-4-39-0-documentation"></a>
Create a CACHEDIR.TAG file in the tox work directory ( .tox ) so that backup and archiving tools (e.g., tar --exclude-caches , Borg, restic) can automatically skip it - by @radevika . ( #3334 )
On Windows, ANSI color codes from child processes (like pytest, mypy) are now rendered correctly in terminals by enabling VT100 processing mode for subprocess output streams - by @gaborbernat . ( #2337 )
Concurrent tox processes no longer corrupt the provision environment ( .tox ) – a file lock now serializes provisioning across processes - by @gaborbernat . ( #2515 )
Config files ( tox.ini , setup.cfg ) with unicode characters are now read correctly on Windows when running tox with python -m -I (isolation mode) - by @gaborbernat . ( #2692 )
set_env values explicitly defined in a section now take precedence over values inherited via cross-section substitution (e.g., {[testenv]set_env} ) - by @gaborbernat . ( #2831 )
The -e flag now supports brace expansion (e.g. tox -e 'py{38,39}-pytest{6.x,7.x}' ) instead of incorrectly splitting on commas inside braces - by @gaborbernat . ( #2850 )
Posargs containing colons no longer crash tox when an inactive environment uses {posargs} in path-like configuration values such as env_dir - by @gaborbernat . ( #2860 )
set_env values from cross-section substitution (e.g., {[testenv]set_env} ) now correctly override default environment variables like PYTHONHASHSEED - by @gaborbernat . ( #2872 )
--force-dep now applies to package dependencies from project metadata (e.g. setup.cfg install_requires , pyproject.toml dependencies ), not just tox config deps - by @gaborbernat . ( #2943 )
Using {posargs} in change_dir no longer causes a RecursionError - by @gaborbernat . ( #3062 )
Cross-section substitution (e.g. {[testenv:a]commands} ) now resolves environment-specific variables like {envpython} , {envbindir} , {envtmpdir} , and {envsitepackagesdir} in the calling environment’s context rather than the referenced environment’s context - by @gaborbernat . ( #3075 )
Fix ValueError crash when using posargs on Windows with subst drive mappings – os.path.relpath fails across drive letters, so fall back to absolute paths when the relative path cannot be computed - by @gaborbernat . ( #3086 )
TOX_OVERRIDE with += (append) now works correctly when the override key name differs from the config file key name (e.g., overriding pass_env when config uses passenv , or vice versa) - by @gaborbernat . ( #3127 )
Fix spurious environment discovery from non-tox sections in setup.cfg – packages = find: in [options] was incorrectly interpreted as a tox factor marker, creating a phantom find environment - by @gaborbernat . ( #3134 )
Requirements in requires with environment markers that evaluate to false (e.g. virtualenv<20.22.0; python_version < "3.8" ) are now correctly skipped during provisioning instead of causing an infinite provisioning loop - by @gaborbernat . ( #3136 )
Running environments with recreate = true no longer destroys shared package environments (e.g. .pkg ), which previously caused FileNotFoundError when a subsequent environment tried to use the already-built wheel - by @gaborbernat . ( #3146 )
Factor-conditional config values (e.g. base_python = py312: python3.12 ) now correctly fall back to the default when no factors match the current environment, instead of producing an empty value - by @gaborbernat . ( #3189 )
TOX_PARALLEL_NO_SPINNER / --parallel-no-spinner no longer forces parallel mode in the legacy command, fixing output suppression for sequential runs in CI - by @gaborbernat . ( #3193 )
Multiple -e flags are now additive ( tox r -e a -e b runs both a and b ), matching tox 3 behavior - by @gaborbernat . ( #3199 )
Environments like functional-py312 no longer incorrectly match when only functional{-py310} is defined as a testenv section – factors from section headers are no longer treated as freely combinable with CLI -e selections by @gaborbernat . ( #3219 )
On Windows, a trailing path separator (e.g. from {/} ) no longer causes the next command argument to be merged into the path - backslash before whitespace is now treated as a literal path separator rather than a space escape - by @gaborbernat . ( #3222 )
Fix {envtmpdir} and other env variable substitutions not expanding in external package environment commands - by @gaborbernat . ( #3238 ) ( #3238 )
On Windows, colored output is now preserved when running provisioned tox by explicitly passing the --colored yes flag to the provisioned subprocess when the parent has colors enabled - by @gaborbernat . ( #3331 )
set_env values defined after a file| reference now correctly take precedence over values loaded from the env file - by @gaborbernat . ( #3335 )
The base configuration key now works correctly in TOML format ( tox.toml and pyproject.toml ), allowing environments to inherit from arbitrary sections defined under [env.*] - by @gaborbernat . ( #3497 )
Skip toxfile.py inline plugin when it uses hooks not available in the current tox version instead of crashing - this allows provisioning to upgrade tox to a version that supports those hooks - by @gaborbernat . ( #3593 )
set_env substitution referencing {envsitepackagesdir} , {envbindir} , or {envpython} for environments with missing interpreters now raises Skip instead of RuntimeError , allowing skip_missing_interpreters to work correctly - by @gaborbernat . ( #3597 )
A setup.cfg without a [tox:tox] section no longer blocks discovery of pyproject.toml or tox.toml configuration files in the same directory - by @gaborbernat . ( #3602 )
Fix pytest INTERNALERROR on Python 3.15 caused by Pygments using deprecated os.path.commonprefix() - by @gaborbernat . ( #3733 )
Fix RecursionError when TOML set_env contains substitutions like {env_site_packages_dir} that trigger config loading cycles – the TOML loader now defers string substitution in set_env values, matching the INI loader’s lazy resolution behavior - by @gaborbernat . ( #3758 )
Document that interactive terminal programs (e.g., IPython) may not work correctly under tox due to the PTY-based output capture architecture - by @gaborbernat . ( #2999 )
Create a CACHEDIR.TAG file in the tox work directory (.tox) so that backup and archiving tools (e.g., tar --exclude-caches, Borg, restic) can automatically skip it - by radevika. (3334)
On Windows, ANSI color codes from child processes (like pytest, mypy) are now rendered correctly in terminals by enabling VT100 processing mode for subprocess output streams - by gaborbernat. (2337)
Concurrent tox processes no longer corrupt the provision environment (.tox) -- a file lock now serializes provisioning across processes - by gaborbernat. (2515)
Config files (tox.ini, setup.cfg) with unicode characters are now read correctly on Windows when running tox with python -m -I (isolation mode) - by gaborbernat. (2692)
set_env values explicitly defined in a section now take precedence over values inherited via cross-section substitution (e.g., {[testenv]set_env}) - by gaborbernat. (2831)
The -e flag now supports brace expansion (e.g. tox -e 'py{38,39}-pytest{6.x,7.x}') instead of incorrectly splitting on commas inside braces - by gaborbernat. (2850)
Posargs containing colons no longer crash tox when an inactive environment uses {posargs} in path-like configuration values such as env_dir - by gaborbernat. (2860)
set_env values from cross-section substitution (e.g., {[testenv]set_env}) now correctly override default environment variables like PYTHONHASHSEED - by gaborbernat. (2872)
--force-dep now applies to package dependencies from project metadata (e.g. setup.cfg install_requires, pyproject.toml dependencies), not just tox config deps - by gaborbernat. (2943)
Using {posargs} in change_dir no longer causes a RecursionError - by gaborbernat. (3062)
Cross-section substitution (e.g. {[testenv:a]commands}) now resolves environment-specific variables like {envpython}, {envbindir}, {envtmpdir}, and {envsitepackagesdir} in the calling environment's context rather than the referenced environment's context - by gaborbernat. (3075)
Fix ValueError crash when using posargs on Windows with subst drive mappings -- os.path.relpath fails across drive letters, so fall back to absolute paths when the relative path cannot be computed - by gaborbernat. (3086)
TOX_OVERRIDE with += (append) now works correctly when the override key name differs from the config file key name (e.g., overriding pass_env when config uses passenv, or vice versa) - by gaborbernat. (3127)
Fix spurious environment discovery from non-tox sections in setup.cfg -- packages = find: in [options] was incorrectly interpreted as a tox factor marker, creating a phantom find environment - by gaborbernat. (3134)
Requirements in requires with environment markers that evaluate to false (e.g. virtualenv<20.22.0; python_version < "3.8") are now correctly skipped during provisioning instead of causing an infinite provisioning loop - by gaborbernat. (3136)
Running environments with recreate = true no longer destroys shared package environments (e.g. .pkg), which previously caused FileNotFoundError when a subsequent environment tried to use the already-built wheel - by gaborbernat. (3146)
Factor-conditional config values (e.g. base_python = py312: python3.12) now correctly fall back to the default when no factors match the current environment, instead of producing an empty value - by gaborbernat. (3189)
TOX_PARALLEL_NO_SPINNER / --parallel-no-spinner no longer forces parallel mode in the legacy command, fixing output suppression for sequential runs in CI - by gaborbernat. (3193)
Multiple -e flags are now additive (tox r -e a -e b runs both a and b), matching tox 3 behavior - by gaborbernat. (3199)
Environments like functional-py312 no longer incorrectly match when only functional{-py310} is defined as a testenv section -- factors from section headers are no longer treated as freely combinable with CLI -e selections by gaborbernat. (3219)
On Windows, a trailing path separator (e.g. from {/}) no longer causes the next command argument to be merged into the path - backslash before whitespace is now treated as a literal path separator rather than a space escape - by gaborbernat. (3222)
Fix {envtmpdir} and other env variable substitutions not expanding in external package environment commands - by gaborbernat. (3238) (3238)
On Windows, colored output is now preserved when running provisioned tox by explicitly passing the --colored yes flag to the provisioned subprocess when the parent has colors enabled - by gaborbernat. (3331)
set_env values defined after a file| reference now correctly take precedence over values loaded from the env file - by gaborbernat. (3335)
The base configuration key now works correctly in TOML format (tox.toml and pyproject.toml), allowing environments to inherit from arbitrary sections defined under [env.*] - by gaborbernat. (3497)
Skip toxfile.py inline plugin when it uses hooks not available in the current tox version instead of crashing - this allows provisioning to upgrade tox to a version that supports those hooks - by gaborbernat. (3593)
set_env substitution referencing {envsitepackagesdir}, {envbindir}, or {envpython} for environments with missing interpreters now raises Skip instead of RuntimeError, allowing skip_missing_interpreters to work correctly - by gaborbernat. (3597)
A setup.cfg without a [tox:tox] section no longer blocks discovery of pyproject.toml or tox.toml configuration files in the same directory - by gaborbernat. (3602)
Fix pytest INTERNALERROR on Python 3.15 caused by Pygments using deprecated os.path.commonprefix() - by gaborbernat. (3733)
Fix RecursionError when TOML set_env contains substitutions like {env_site_packages_dir} that trigger config loading cycles -- the TOML loader now defers string substitution in set_env values, matching the INI loader's lazy resolution behavior - by gaborbernat. (3758)
Document that interactive terminal programs (e.g., IPython) may not work correctly under tox due to the PTY-based output capture architecture - by gaborbernat. (2999)
Scope dependency rejection in PEP-517 package environments to only pure PEP-517 build types (sdist, wheel, editable), allowing non-standard package ty
<a name="release-4-38-0-added"></a>
sdist, wheel, editable), allowing non-standard package types like editable-legacy to specify dependencies by @rahuldevikar. (#3731)Scope dependency rejection in PEP-517 package environments to only pure PEP-517 build types (sdist, wheel, editable), allowing non-standard package types like editable-legacy to specify dependencies - by rahuldevikar. (3731)
Add extra_setup_commands configuration option to run commands after dependency and package installation but before test commands, useful with --notest
<a name="release-4-37-0-added"></a>
extra_setup_commands configuration option to run commands after dependency and package installation but before test commands, useful with --notest for separating setup from execution by @gaborbernat. (#1504)<a name="release-4-37-0-fixed"></a>
PIP_USER=0 environment variable when running pip commands in virtualenvs to prevent pip from attempting --user installs when users have pip config --user configured globally — by @gaborbernat. (#3010)extras = snake_case now matches Provides-Extra: snake-case in wheel metadata) by @Fridayai700. (#3433)setenv modifications to PATH being overwritten when tox environment paths are set up by @Fridayai700 (#3445)deps entries with ~= version specifier being incorrectly treated as local paths instead of being passed through to pip by @Fridayai700. (#3447)TOX_FACTORS environment variable producing wrong results because append + nargs="+" actions need nested list types for proper env var conversion by @Fridayai700. (#3557)install_command being ignored when specified in TOML configuration (tox.toml/pyproject.toml) by @Fridayai700. (#3574)py3.11) losing their description in TOML configuration by @Fridayai700. (#3590)completion extras to type and type-min environments so ty can resolve the argcomplete import by @gaborbernat. (#3728)<a name="release-4-37-0-documentation"></a>
Add extra_setup_commands configuration option to run commands after dependency and package installation but before test commands, useful with --notest for separating setup from execution - by gaborbernat. (1504)
Set PIP_USER=0 environment variable when running pip commands in virtualenvs to prevent pip from attempting --user installs when users have pip config --user configured globally — by gaborbernat. (3010)
Fix TOML env_run_base and env_pkg_base deps being clobbered when referenced with additional deps in testenv configuration (3393)
Normalize extra names when resolving dependencies so that underscores and hyphens are treated equivalently (e.g. extras = snake_case now matches Provides-Extra: snake-case in wheel metadata) - by Fridayai700. (3433)
Fix setenv modifications to PATH being overwritten when tox environment paths are set up - by Fridayai700 (3445)
Fix deps entries with ~= version specifier being incorrectly treated as local paths instead of being passed through to pip - by Fridayai700. (3447)
Fix factor selection via TOX_FACTORS environment variable producing wrong results because append + nargs="+" actions need nested list types for proper env var conversion - by Fridayai700. (3557)
Fix custom install_command being ignored when specified in TOML configuration (tox.toml/pyproject.toml) - by Fridayai700. (3574)
Fix env names containing dots (e.g. py3.11) losing their description in TOML configuration - by Fridayai700. (3590)
Run pre-commit on changelog.rst after towncrier build to ensure proper formatting before committing the release (3717)
Fix type checker CI failure by adding completion extras to type and type-min environments so ty can resolve the argcomplete import - by gaborbernat. (3728)
Restructured documentation using the Diátaxis framework to separate Tutorial, How-to guides, Reference, and Explanation content for better discoverability and user experience. (3718)
Report TOML parse errors during config discovery instead of silently ignoring them by @rahuldevikar.
<a name="release-4-36-1-fixed"></a>
<a name="release-4-36-1-documentation"></a>
logging for plugin authors in the how-to guides, covering verbosity levels, coloring, and best practices — by @rahuldevikar. (#3449)Report TOML parse errors during config discovery instead of silently ignoring them - by rahuldevikar. (3030)
Adopt CPython's subprocess stream handling to fix deadlocks and improve performance when reading subprocess output (3715)
Add Unix man page generation and installation support using sphinx-argparse-cli - by gaborbernat. (1409)
Document use of Python logging for plugin authors in the how-to guides, covering verbosity levels, coloring, and best practices — by rahuldevikar. (3449)
Add architecture documentation for new contributors under the development section - by rahuldevikar (3707)
Allow skip_missing_interpreters to be set per environment, overriding the global setting. This enables marking specific environments as optional while
<a name="release-4-36-0-added"></a>
skip_missing_interpreters to be set per environment, overriding the global setting. This enables marking specific environments as optional while keeping others required. (#435)--fail-fast CLI flag and fail_fast per-environment config option to stop executing remaining environments when the first failure occurs by @gaborbernat. (#578)argcomplete by @gaborbernat (#918)depends (e.g. depends = py3*) to match environments by wildcard instead of listing them explicitly by @gaborbernat (#1152)disallow_pass_env configuration option to exclude specific environment variables after pass_env glob expansion by @gaborbernat (#1387)file: URIs in --installpkg (e.g. --installpkg file:///path/to/pkg.whl), including proper handling of percent-encoded characters by @rahuldevikar. (#3498)tox r -e release command by @gaborbernat (#3704)<a name="release-4-36-0-changes"></a>
mypy to ty by @gaborbernat. (#3685)<a name="release-4-36-0-fixed"></a>
deps is configured on a PEP-517 packaging environment (e.g. .pkg), since build dependencies should be specified via the [build-system] table in pyproject.toml by @rahuldevikar (#3412)yes, true, or 1 were accepted, and other values caused a crash). Also add support for TTY_COMPATIBLE (1 forces color, 0 disables it) — by @rahuldevikar. (#3579)<a name="release-4-36-0-documentation"></a>
toxfile.py inline plugins using tox_extend_envs and MemoryLoader by @gaborbernat. (#828){...} replacement variables by @gaborbernat (#3326)tox.toml and pyproject.toml formats, and emphasize TOML as the recommended format throughout by @gaborbernat (#3393)tox exec subcommand with usage examples in the how-to guides by @gaborbernat (#3403)development.rst to reflect current standards: replace references to flake8/black/isort/pyupgrade with ruff, remove outdated Python 2.7 compatibility note, and fix CI config filename by @rahuldevikar (#3483)setup.py mentions from the installation page — by @rahuldevikar. (#3588)getting_started.rst), consolidate how-to recipes (howto.rst), refocus the user guide on conceptual explanation, and move plugin docs into their own plugins/ subdirectory. Remove the obsolete tox 3-to-4 migration guide (upgrading.rst) and FAQ, redistributing still-relevant content into the appropriate sections. All configuration examples now show TOML first with INI alongside by @gaborbernat (#3702)Allow skip_missing_interpreters to be set per environment, overriding the global setting. This enables marking specific environments as optional while keeping others required. (435)
Add --fail-fast CLI flag and fail_fast per-environment config option to stop executing remaining environments when the first failure occurs - by gaborbernat. (578)
Add shell completion support for bash, zsh, and fish via argcomplete - by gaborbernat (918)
Validate that configured extras exist in package metadata, raising a clear error for unknown extras - by gaborbernat (1113)
Add glob pattern support in depends (e.g. depends = py3*) to match environments by wildcard instead of listing them explicitly - by gaborbernat (1152)
Add disallow_pass_env configuration option to exclude specific environment variables after pass_env glob expansion - by gaborbernat (1387)
Support file: URIs in --installpkg (e.g. --installpkg file:///path/to/pkg.whl), including proper handling of percent-encoded characters - by rahuldevikar. (3498)
Add GitHub Actions workflow dispatch for release preparation as alternative to local tox r -e release command - by gaborbernat (3704)
Switch type checker from mypy to ty - by gaborbernat. (3685)
Raise an error when deps is configured on a PEP-517 packaging environment (e.g. .pkg), since build dependencies should be specified via the [build-system] table in pyproject.toml - by rahuldevikar (3412)
Follow FORCE_COLOR recommendations: any non-empty value now enables color (previously only yes, true, or 1 were accepted, and other values caused a crash). Also add support for TTY_COMPATIBLE (1 forces color, 0 disables it) — by rahuldevikar. (3579)
Return non-zero exit code from tox config when configuration exceptions occur. (3649)
Fix flaky spinner test assertion caused by timing variations on slower systems. (3692)
Document how to provide environments via toxfile.py inline plugins using tox_extend_envs and MemoryLoader by gaborbernat. (828)
Document shell completion setup for bash, zsh, and fish in the CLI reference - by gaborbernat (918)
Document negative factor conditions and multi-factor combinations with negation in the INI configuration reference - by gaborbernat (3276)
Add a substitution quick reference table covering all available {...} replacement variables - by gaborbernat (3326)
Add TOML configuration reference with complete examples for tox.toml and pyproject.toml formats, and emphasize TOML as the recommended format throughout - by gaborbernat (3393)
Document the tox exec subcommand with usage examples in the how-to guides - by gaborbernat (3403)
Comprehensive documentation improvements: added how-to guides for tox exec, CI/CD, coverage, build backends, labels, migration, debugging, and extras; expanded plugin documentation with all hook examples and packaging guide; added env var handling guide, factor conditions reference, and substitution quick reference; integrated docstrfmt for consistent RST formatting; fixed docstring issues in source code - by gaborbernat (3475)
Update development.rst to reflect current standards: replace references to flake8/black/isort/pyupgrade with ruff, remove outdated Python 2.7 compatibility note, and fix CI config filename - by rahuldevikar (3483)
Drop setup.py mentions from the installation page — by rahuldevikar. (3588)
Restructure documentation following the Diataxis framework: add a step-by-step tutorial (getting_started.rst), consolidate how-to recipes (howto.rst), refocus the user guide on conceptual explanation, and move plugin docs into their own plugins/ subdirectory. Remove the obsolete tox 3-to-4 migration guide (upgrading.rst) and FAQ, redistributing still-relevant content into the appropriate sections. All configuration examples now show TOML first with INI alongside - by gaborbernat (3702)
Show toxfile.py inline plugins in tox --version output, including any tox_append_version_info() result by @rahuldevikar.
<a name="release-4-35-0-added"></a>
toxfile.py inline plugins in tox --version output, including any tox_append_version_info() result by @rahuldevikar. (#3508)<a name="release-4-35-0-documentation"></a>
TOX_ENV_NAME, TOX_WORK_DIR, TOX_ENV_DIR, TOX_PACKAGE, VIRTUAL_ENV, PYTHONIOENCODING, __TOX_ENVIRONMENT_VARIABLE_ORIGINAL_CI) that tox automatically sets when running commands by @rahuldevikar. (#3514)Show toxfile.py inline plugins in tox --version output, including any tox_append_version_info() result - by rahuldevikar. (3508)
Document injected environment variables (TOX_ENV_NAME, TOX_WORK_DIR, TOX_ENV_DIR, TOX_PACKAGE, VIRTUAL_ENV, PYTHONIOENCODING, __TOX_ENVIRONMENT_VARIABLE_ORIGINAL_CI) that tox automatically sets when running commands - by rahuldevikar. (3514)
Fix wheel corruption errors when the build backend updates the file in place by @gaborbernat.
<a name="release-4-34-1-fixed"></a>
Fix wheel corruption errors when the build backend updates the file in place - by gaborbernat. (3667)
Support installing extras from the current project in dependency groups. -- by @czaki.
<a name="release-4-34-0-added"></a>
Support installing extras from the current project in dependency groups. -- by czaki. (3561)
Add support for conditional set_env using PEP-496 environment markers. In INI format use VAR=value; marker syntax, in TOML format use set_env.VAR = {
<a name="release-4-33-0-added"></a>
set_env using PEP-496 environment markers. In INI format use VAR=value; marker syntax, in TOML format use set_env.VAR = { value = "...", marker = "..." } -- by @gaborbernat. (#3663)<a name="release-4-33-0-fixed"></a>
<a name="release-4-33-0-documentation"></a>
sphinx-issues for referencing GitHub issues and pull requests in the docs -- by @webknjaz. (#3202)Add support for conditional set_env using PEP-496 environment markers. In INI format use VAR=value; marker syntax, in TOML format use set_env.VAR = { value = "...", marker = "..." } -- by gaborbernat. (3663)
Added 'LocalAppData' to the default passed environment variables on Windows. (3639)
Sphinx is now set up to use sphinx-issues for referencing GitHub issues and pull requests in the docs -- by webknjaz. (3202)
Expand braced range syntax in all internal sections of tox.ini (e.g. deps, testenv). Syntax like py3{10-14} can be used in those sections now. by @mar
<a name="release-4-32-0-fixed"></a>
tox.ini (e.g. deps, testenv). Syntax like py3{10-14} can be used in those sections now. by @marcosboger (#3571)<a name="release-4-32-0-documentation"></a>
Expand braced range syntax in all internal sections of tox.ini (e.g. deps, testenv). Syntax like py3{10-14} can be used in those sections now. - by marcosboger (3571)
Add Python 3.14 and 3.14t to config examples - by cclauss (3626)
🐍 PyPI release 📜 Full Changelog
Fix incorrect type annotation in PythonPathPackageWithDeps.__init__() where deps was annotated as Sequence[Package] but should be Sequence[Requirement
<a name="release-4-30-3-fixed"></a>
PythonPathPackageWithDeps.__init__() where deps was annotated as Sequence[Package] but should be Sequence[Requirement] to match actual runtime usage by @PreistlyPython (#3607)None appearing as the config filename in error output when the user's default config file is corrupt. by @kurtmckee (#3611)Fix incorrect type annotation in PythonPathPackageWithDeps.__init__() where deps was annotated as Sequence[Package] but should be Sequence[Requirement] to match actual runtime usage - by PreistlyPython (3607)
Fix None appearing as the config filename in error output when the user's default config file is corrupt. - by kurtmckee (3611)
Previously, when tox ran in an automatically provisioned environment, it could hang waiting for a PEP 517 build backend if used in conjunction with th
<a name="release-4-30-2-fixed"></a>
Previously, when tox ran in an automatically provisioned environment, it could hang waiting for a PEP 517 build backend if used in conjunction with the --installpkg option. This has been fixed by properly tearing down the automatically provisioned environment after the tests. - by vytas7 (3600)
Prevent tox from hanging upon exit due to orphaned build threads and subprocesses when the --installpkg option is used with *sdist*. by @vytas7
Prevent tox from hanging upon exit due to orphaned build threads and subprocesses when the --installpkg option is used with sdist. - by vytas7 (3530)
Add __TOX_ENVIRONMENT_VARIABLE_ORIGINAL_CI, which passes through the CI variable if present. This is intended for use by other libraries to detect if
<a name="release-4-30-0-added"></a>
__TOX_ENVIRONMENT_VARIABLE_ORIGINAL_CI, which passes through the CI variable if present. This is intended for use by other libraries to detect if tox is running under CI. (#3442)<a name="release-4-30-0-fixed"></a>
tox_extend_envs() hook recently added in #3591 turned out to not work well with tox run. It was fixed internally, not to exhaust the underlying iterator on the first use. -- by @webknjaz (#3598)Add __TOX_ENVIRONMENT_VARIABLE_ORIGINAL_CI, which passes through the CI variable if present. This is intended for use by other libraries to detect if tox is running under CI. (3442)
Makes the error message more clear when pyproject.toml file cannot be loaded or is missing expected keys. (3578)
The tox_extend_envs() hook recently added in 3591 turned out to not work well with tox run. It was fixed internally, not to exhaust the underlying iterator on the first use. -- by webknjaz (3598)
A new tox life cycle event is now exposed for use via Plugins API -- by @webknjaz. The corresponding hook point is tox_extend_envs. It allows plugin a
<a name="release-4-29-0-added"></a>
Plugins API -- by @webknjaz. The corresponding hook point is tox_extend_envs. It allows plugin authors to declare ephemeral environments that they can then populate through the in-memory configuration loader interface. This patch was made possible thanks to pair programming with @gaborbernat at PyCon US 2025. (#3510, #3591)A new tox life cycle event is now exposed for use via Plugins API -- by webknjaz. The corresponding hook point is tox_extend_envs. It allows plugin authors to declare ephemeral environments that they can then populate through the in-memory configuration loader interface. This patch was made possible thanks to pair programming with gaborbernat at PyCon US 2025. (3510, 3591)
Pass ssh-agent variables SSH_AGENT_PID and SSH_AUTH_SOCK in pass_env by default. by @daniilgankov
<a name="release-4-28-4-added"></a>
SSH_AGENT_PID and SSH_AUTH_SOCK in pass_env by default. by @daniilgankov (#3572)Pass ssh-agent variables SSH_AGENT_PID and SSH_AUTH_SOCK in pass_env by default. - by daniilgankov (3572)
🐍 PyPI release 📜 Full Changelog
Don't pass in the filter argument to tar.extractall on old Python versions by @gaborbernat.
<a name="release-4-28-2-fixed"></a>
Don't pass in the filter argument to tar.extractall on old Python versions - by gaborbernat. (3568)
Use tarfile.data_filter with extractall only on supported Python versions:
<a name="release-4-28-1-fixed"></a>
extractall only on supported Python versions:
>= 3.11.4>= 3.10.12 and < 3.11>= 3.9.17 and < 3.10 by @gaborbernat. (#3565)Use tarfile.data_filter with extractall only on supported Python versions:
>= 3.11.4
>= 3.10.12 and < 3.11
>= 3.9.17 and < 3.10 by gaborbernat. (3565)
The min_version/minversion config option is deprecated in favor of the requires option.
<a name="release-4-28-0-added"></a>
constraints to allow specifying constraints files for all dependencies. (#3550)TOX_DISABLED_EXTERNAL_PLUGINS environment variable by @gaborbernat. (#3468)<a name="release-4-28-0-documentation"></a>
min_version/minversion config option is deprecated in favor of the requires option. (#3553)Added constraints to allow specifying constraints files for all dependencies. (3550)
Allow disabling tox plugins via the TOX_DISABLED_EXTERNAL_PLUGINS environment variable - by gaborbernat. (3468)
The min_version/minversion config option is deprecated in favor of the requires option. (3553)
Add free_threaded flag to to "python" entries in json output of --result-json.
<a name="release-4-27-0-added"></a>
free_threaded flag to to "python" entries in json output of --result-json. (#3534)<a name="release-4-27-0-fixed"></a>
Add free_threaded flag to to "python" entries in json output of --result-json. (3534)
Fix dependency-group name normalization. (3539)
Improves logging of environment variables by sorting them by key and redacting the values for the ones that are likely to contain secrets. (3542)
Add support for free-threaded python builds. Factors like py313t will only pick builds with the GIL disabled while factors without trailing t will onl
<a name="release-4-26-0-added"></a>
py313t will only pick builds with the GIL disabled while factors without trailing t will only pick builds without no-GIL support. (#3391)<a name="release-4-26-0-fixed"></a>
file| substitution option in nested set_env sections of ini configurations since tox4 update. (#2435)TypeError for HelpFormatter with Python 3.14 (#3523)Add support for free-threaded python builds. Factors like py313t will only pick builds with the GIL disabled while factors without trailing t will only pick builds without no-GIL support. (3391)
Drop support for EOL Python 3.8. (3527)
Fix a regression issue related to inability to use file| substitution option in nested set_env sections of ini configurations since tox4 update. (2435)
Fix TypeError for HelpFormatter with Python 3.14 (3523)
Add support for number ranges in generative environments, more details here. by @mimre25
<a name="release-4-25-0-added"></a>
<a name="release-4-25-0-fixed"></a>
Add support for number ranges in generative environments, more details here . - by @mimre25 ( #3502 )
Make tox tests pass with Python 3.14.0a6 - by @hroncok ( #3500 )
Add support for number ranges in generative environments, more details here. - by mimre25 (3502)
Make tox tests pass with Python 3.14.0a6 - by hroncok (3500)
multiple source_type supports for the same filename. Like pyproject.toml can be load by both TomlPyProject & LegacyToml
<a name="release-4-24-2-fixed"></a>
set_env = { file = "conf{/}local.env"} for TOML format by @juditnovak. (#3474)--parallel-no-spinner now respects max CPU set by --parallel N (#3495)<a name="release-4-24-2-documentation"></a>
os.environ['KEY'] when the variable does not exist by @jugmac00. (#3456)multiple source_type supports for the same filename. Like pyproject.toml can be load by both TomlPyProject & LegacyToml (3117)
Support set_env = { file = "conf{/}local.env"} for TOML format - by juditnovak. (3474)
fix example on the docs (3480)
--parallel-no-spinner now respects max CPU set by --parallel N (3495)
Updates the documentation for os.environ['KEY'] when the variable does not exist - by jugmac00. (3456)
🐍 PyPI release 📜 Full Changelog
Add a schema command to produce a JSON Schema for tox and the current plugins. by @henryiii
<a name="release-4-24-0-added"></a>
<a name="release-4-24-0-fixed"></a>
<a name="release-4-24-0-documentation"></a>
docs/config.rst from {} to {:}. by @wooshaun53 (#3424)NIX_LD and NIX_LD_LIBRARY_PATH variables by default in pass_env to make generic binaries work under Nix/NixOS. by @albertodonato (#3425)Add a schema command to produce a JSON Schema for tox and the current plugins. - by henryiii (3446)
Log exception name when subprocess execution produces one. - by ssbarnea (3450)
Fix typo in docs/config.rst from {} to {:}. - by wooshaun53 (3424)
Pass NIX_LD and NIX_LD_LIBRARY_PATH variables by default in pass_env to make generic binaries work under Nix/NixOS. - by albertodonato (3425)
@mbra made their first contribution in #3422
Fix bad example in documentation for dependency groups by @gaborbernat.
<a name="release-4-23-1-documentation"></a>
Fix bad example in documentation for dependency groups - by gaborbernat. (3240)
Add NETRC to the list of environment variables always passed through.
<a name="release-4-23-0-added"></a>
NETRC to the list of environment variables always passed through. (#3410)<a name="release-4-23-0-documentation"></a>
[tool.pyproject] and [tool.tox.pyproject] with [tool.tox] in config.rst (#3411)Add NETRC to the list of environment variables always passed through. (3410)
replace [tool.pyproject] and [tool.tox.pyproject] with [tool.tox] in config.rst (3411)
Implement dependency group support as defined in PEP 735 - see dependency_groups by @gaborbernat.
<a name="release-4-22-0-added"></a>
dependency_groups by @gaborbernat. (#3408)Implement dependency group support as defined in PEP 735 - see dependency_groups - by gaborbernat. (3408)
Include tox.toml in sdist archives to fix test failures resulting from its lack. by @mgorny
<a name="release-4-21-2-fixed"></a>
Include tox.toml in sdist archives to fix test failures resulting from its lack. - by mgorny (3389)
Fix error when using requires within a TOML configuration file by @gaborbernat.
<a name="release-4-21-1-fixed"></a>
requires within a TOML configuration file by @gaborbernat. (#3386)deps within a TOML configuration file by @gaborbernat. (#3387)commands.set_env by accepting list of dictionaries for it.extend flag, available both for posargs and ref replacements.ref replacements raw key has been renamed to of. (#3388)Fix error when using requires within a TOML configuration file - by gaborbernat. (3386)
Fix error when using deps within a TOML configuration file - by gaborbernat. (3387)
Multiple fixes for the TOML configuration by gaborbernat.:
Do not fail when there is an empty command within commands.
Allow references for set_env by accepting list of dictionaries for it.
Do not try to be smart about reference unrolling, instead allow the user to control it via the extend flag, available both for posargs and ref replacements.
The ref replacements raw key has been renamed to of. (3388)
Native TOML configuration support by @gaborbernat.
<a name="release-4-21-0-added"></a>
<a name="release-4-21-0-documentation"></a>
Native TOML configuration support - by gaborbernat. (999)
Update Loader docs - by :user:ziima (3352)
One column per quarter.