pytest 9.0.0 (2025-11-05)
New features
- \#1367: Support for subtests has been added.
subtests <subtests> are an alternative to parametrization, useful in situations where the parametrization values are not all known at collection time.
Example:
def contains_docstring(p: Path) -> bool:
"""Return True if the given Python file contains a top-level docstring."""
...
def test_py_files_contain_docstring(subtests: pytest.Subtests) -> None:
for path in Path.cwd().glob("*.py"):
with subtests.test(path=str(path)):
assert contains_docstring(path)
Each assert failure or error is caught by the context manager and reported individually, giving a clear picture of all files that are missing a docstring.
In addition, unittest.TestCase.subTest is now also supported.
This feature was originally implemented as a separate plugin in pytest-subtests, but since then has been merged into the core.
> [!NOTE] > This feature is experimental and will likely evolve in future releases. By that we mean that we might change how subtests are reported on failure, but the functionality and how to use it are stable.
- \#13743: Added support for native TOML configuration files.
While pytest, since version 6, supports configuration in pyproject.toml files under [tool.pytest.ini_options], it does so in an "INI compatibility mode", where all configuration values are treated as strings or list of strings. Now, pytest supports the native TOML data model.
In pyproject.toml, the native TOML configuration is under the [tool.pytest] table.
# pyproject.toml
[tool.pytest]
minversion = "9.0"
addopts = ["-ra", "-q"]
testpaths = [
"tests",
"integration",
]
The [tool.pytest.ini_options] table remains supported, but both tables cannot be used at the same time.
If you prefer to use a separate configuration file, or don't use pyproject.toml, you can use pytest.toml or .pytest.toml:
# pytest.toml or .pytest.toml
[pytest]
minversion = "9.0"
addopts = ["-ra", "-q"]
testpaths = [
"tests",
"integration",
]
The documentation now (sometimes) shows configuration snippets in both TOML and INI formats, in a tabbed interface.
See config file formats for full details.
- \#13823: Added a "strict mode" enabled by the
strict configuration option.
When set to true, the strict option currently enables
strict_configstrict_markersstrict_parametrization_idsstrict_xfail
The individual strictness options can be explicitly set to override the global strict setting.
The previously-deprecated --strict command-line flag now enables strict mode.
If pytest adds new strictness options in the future, they will also be enabled in strict mode. Therefore, you should only enable strict mode if you use a pinned/locked version of pytest, or if you want to proactively adopt new strictness options as they are added.
See strict mode for more details.
- \#13737: Added the
strict_parametrization_ids configuration option.
When set, pytest emits an error if it detects non-unique parameter set IDs, rather than automatically making the IDs unique by adding <span class="title-ref">0</span>, <span class="title-ref">1</span>, ... to them. This can be particularly useful for catching unintended duplicates.
- \#13072: Added support for displaying test session progress in the terminal tab using the OSC 9;4; ANSI sequence. When pytest runs in a supported terminal emulator like ConEmu, Gnome Terminal, Ptyxis, Windows Terminal, Kitty or Ghostty, you'll see the progress in the terminal tab or window, allowing you to monitor pytest's progress at a glance.
This feature is automatically enabled when running in a TTY. It is implemented as an internal plugin. If needed, it can be disabled as follows:
- On a user level, using
-p no:terminalprogress on the command line or via an environment variable PYTEST_ADDOPTS='-p no:terminalprogress'.
- On a project configuration level, using
addopts = "-p no:terminalprogress".
- \#478: Support PEP420 (implicit namespace packages) as <span class="title-ref">--pyargs</span> target when
consider_namespace_packages is <span class="title-ref">true</span> in the config.
Previously, this option only impacted package imports, now it also impacts tests discovery.
- \#13678: Added a new
faulthandler_exit_on_timeout configuration option set to "false" by default to let <span class="title-ref">faulthandler</span> interrupt the <span class="title-ref">pytest</span> process after a timeout in case of deadlock.
Previously, a <span class="title-ref">faulthandler</span> timeout would only dump the traceback of all threads to stderr, but would not interrupt the <span class="title-ref">pytest</span> process.
-- by ogrisel.
- \#13829: Added support for configuration option aliases via the
aliases parameter in Parser.addini() <pytest.Parser.addini>.
Plugins can now register alternative names for configuration options, allowing for more flexibility in configuration naming and supporting backward compatibility when renaming options. The canonical name always takes precedence if both the canonical name and an alias are specified in the configuration file.
Improvements in existing functionality
- \#13330: Having pytest configuration spread over more than one file (for example having both a
pytest.ini file and pyproject.toml with a [tool.pytest.ini_options] table) will now print a warning to make it clearer to the user that only one of them is actually used.
-- by sgaist
- \#13574: The single argument
--version no longer loads the entire plugin infrastructure, making it faster and more reliable when displaying only the pytest version.
Passing --version twice (e.g., pytest --version --version) retains the original behavior, showing both the pytest version and plugin information.
> [!NOTE] > Since --version is now processed early, it only takes effect when passed directly via the command line. It will not work if set through other mechanisms, such as PYTEST_ADDOPTS or addopts.
- \#13823: Added
strict_xfail as an alias to the xfail_strict option, strict_config as an alias to the --strict-config flag, and strict_markers as an alias to the --strict-markers flag. This makes all strictness options consistently have configuration options with the prefix strict_.
- \#13700: <span class="title-ref">--junitxml</span> no longer prints the <span class="title-ref">generated xml file</span> summary at the end of the pytest session when <span class="title-ref">--quiet</span> is given.
- \#13732: Previously, when filtering warnings, pytest would fail if the filter referenced a class that could not be imported. Now, this only outputs a message indicating the problem.
- \#13859: Clarify the error message for <span class="title-ref">pytest.raises()</span> when a regex <span class="title-ref">match</span> fails.
- \#13861: Better sentence structure in a test's expected error message. Previously, the error message would be "expected exception must be \<expected\>, but got \<actual\>". Now, it is "Expected \<expected\>, but got \<actual\>".
Removals and backward incompatible breaking changes
- \#12083: Fixed a bug where an invocation such as <span class="title-ref">pytest a/ a/b</span> would cause only tests from <span class="title-ref">a/b</span> to run, and not other tests under <span class="title-ref">a/</span>.
The fix entails a few breaking changes to how such overlapping arguments and duplicates are handled:
1. <span class="title-ref">pytest a/b a/</span> or <span class="title-ref">pytest a/ a/b</span> are equivalent to <span class="title-ref">pytest a</span>; if an argument overlaps another arguments, only the prefix remains. 2. <span class="title-ref">pytest x.py x.py</span> is equivalent to <span class="title-ref">pytest x.py</span>; previously such an invocation was taken as an explicit request to run the tests from the file twice.
If you rely on these behaviors, consider using --keep-duplicates <duplicate-paths>, which retains its existing behavior (including the bug).
- \#13719: Support for Python 3.9 is dropped following its end of life.
- \#13766: Previously, pytest would assume it was running in a CI/CD environment if either of the environment variables <span class="title-ref">\$CI</span> or <span class="title-ref">\$BUILD_NUMBER</span> was defined; now, CI mode is only activated if at least one of those variables is defined and set to a non-empty value.
- \#13779: PytestRemovedIn9Warning deprecation warnings are now errors by default.
Following our plan to remove deprecated features with as little disruption as possible, all warnings of type PytestRemovedIn9Warning now generate errors instead of warning messages by default.
The affected features will be effectively removed in pytest 9.1, so please consult the deprecations section in the docs for directions on how to update existing code.
In the pytest 9.0.X series, it is possible to change the errors back into warnings as a stopgap measure by adding this to your pytest.ini file:
[pytest]
filterwarnings =
ignore::pytest.PytestRemovedIn9Warning
But this will stop working when pytest 9.1 is released.
If you have concerns about the removal of a specific feature, please add a comment to 13779.
Deprecations (removal in next major release)
- \#13807:
monkeypatch.syspath_prepend() <pytest.MonkeyPatch.syspath_prepend> now issues a deprecation warning when the prepended path contains legacy namespace packages (those using pkg_resources.declare_namespace()). Users should migrate to native namespace packages (420). See monkeypatch-fixup-namespace-packages for details.
Bug fixes
- \#13445: Made the type annotations of
pytest.skip and friends more spec-complaint to have them work across more type checkers.
- \#13537: Fixed a bug in which
ExceptionGroup with only Skipped exceptions in teardown was not handled correctly and showed as error.
- \#13598: Fixed possible collection confusion on Windows when short paths and symlinks are involved.
- \#13716: Fixed a bug where a nonsensical invocation like
pytest x.py[a] (a file cannot be parametrized) was silently treated as pytest x.py. This is now a usage error.
- \#13722: Fixed a misleading assertion failure message when using
pytest.approx on mappings with differing lengths.
- \#13773: Fixed the static fixture closure calculation to properly consider transitive dependencies requested by overridden fixtures.
- \#13816: Fixed
pytest.approx which now returns a clearer error message when comparing mappings with different keys.
- \#13849: Hidden
.pytest.ini files are now picked up as the config file even if empty. This was an inconsistency with non-hidden pytest.ini.
- \#13865: Fixed <span class="title-ref">--show-capture</span> with <span class="title-ref">--tb=line</span>.
- \#13522: Fixed
pytester in subprocess mode ignored all :attr\pytester.plugins \<pytest.Pytester.plugins\>\ except the first.
Fixed pytester in subprocess mode silently ignored non-str pytester.plugins <pytest.Pytester.plugins>. Now it errors instead. If you are affected by this, specify the plugin by name, or switch the affected tests to use pytester.runpytest_inprocess <pytest.Pytester.runpytest_inprocess> explicitly instead.
Packaging updates and notes for downstreams
- \#13791: Minimum requirements on
iniconfig and packaging were bumped to 1.0.1 and 22.0.0, respectively.
Contributor-facing changes
- \#12244: Fixed self-test failures when <span class="title-ref">TERM=dumb</span>.
- \#12474: Added scheduled GitHub Action Workflow to run Sphinx linkchecks in repo documentation.
- \#13621: pytest's own testsuite now handles the
lsof command hanging (e.g. due to unreachable network filesystems), with the affected selftests being skipped after 10 seconds.
- \#13638: Fixed deprecated
gh pr new command in scripts/prepare-release-pr.py. The script now uses gh pr create which is compatible with GitHub CLI v2.0+.
- \#13695: Flush <span class="title-ref">stdout</span> and <span class="title-ref">stderr</span> in <span class="title-ref">Pytester.run</span> to avoid truncated outputs in <span class="title-ref">test_faulthandler.py::test_timeout</span> on CI -- by
ogrisel.
- \#13771: Skip <span class="title-ref">test_do_not_collect_symlink_siblings</span> on Windows environments without symlink support to avoid false negatives.
- \#13841:
tox>=4 is now required when contributing to pytest.
- \#13625: Added missing docstrings to
pytest_addoption(), pytest_configure(), and cacheshow() functions in cacheprovider.py.
Miscellaneous internal changes
- \#13830: Configuration overrides (
-o/--override-ini) are now processed during startup rather than during config.getini() <pytest.Config.getini>.