Pytest ini Explained: addopts, markers, testpaths and Precedence
A pytest ini file sets your test options once, so every developer and every CI run behaves the same. We built a small project and ran it with and without pytest.ini to show exactly what testpaths, addopts, strict markers, xfail_strict and filterwarnings change, which config file wins when you have several, and how to override settings from the command line.
- A pytest ini file is a
[pytest]section inpytest.iniat your project root; pytest finds it from any subfolder. - Adding one changed our run from “1 failed, 3 passed, 1 xpassed, 2 warnings” to a strict run that caught three hidden problems.
- With strict markers on, a typo like
@pytest.mark.slowwstopped collection with an error instead of silently doing nothing. - When both pytest.ini and pyproject.toml had settings, pytest 9.2 used pytest.ini and printed a warning that it was ignoring pyproject.toml.
Typing the same options every time you run tests, such as which folder to use, which warnings to treat as errors, or how verbose to be, is tedious and error-prone. Worse, if every developer types something different, the same suite gives different results on different machines. A pytest ini file stores those choices in the repository, so running pytest with no arguments does the right thing everywhere, including CI.
All runs used pytest 9.2.0 on Python 3.13.6, and the outputs are copied from the terminal. If pytest is new to you, start with our pytest tutorial.
What is pytest.ini?
pytest.ini is an INI-format configuration file that pytest reads at start-up. Its settings live under a [pytest] header. The same settings can also go in pyproject.toml under [tool.pytest.ini_options], in tox.ini under [pytest], or in setup.cfg under [tool:pytest]. The directory containing the chosen file becomes the rootdir, which pytest uses for node IDs and the cache.
Our test project
proj/
src/
docs/test_docs.py # a stray helper that happens to look like a test
tests/test_app.py
# tests/test_app.py
import pytest, warnings
def test_fast(): assert 1 + 1 == 2
@pytest.mark.slow
def test_slow(): assert sum(range(10)) == 45
@pytest.mark.xfail(reason="known bug")
def test_known_bug(): assert True # the bug was actually fixed
def test_warns():
warnings.warn("old api", DeprecationWarning)
This small project hides three realistic problems: a file in docs that pytest should not collect, an expected failure that now passes, and code that calls a deprecated API.
Without a config file
pytest -q
FAILED docs/test_docs.py::test_doc_helper - assert False
1 failed, 3 passed, 1 xpassed, 2 warnings
Pytest searched every folder, collected the stray docs file and failed on it. The xfail test quietly passed (xpassed), and the deprecation became a warning that most people scroll past. None of the real issues stopped the build.
The pytest.ini we used
[pytest]
minversion = 8.0
testpaths = tests
addopts = -ra --strict-markers
markers =
slow: marks tests as slow (deselect with -m "not slow")
xfail_strict = true
filterwarnings =
error::DeprecationWarning
Multi-value options such as markers and filterwarnings take one entry per indented line. Comments start with # or ; on their own line.
With the config file
pytest -q
FAILED tests/test_app.py::test_known_bug - [XPASS(strict)] known bug
FAILED tests/test_app.py::test_warns - DeprecationWarning: old api
2 failed, 2 passed
The docs file was no longer collected, the outdated xfail failed loudly, and the deprecated call became a test failure. Each of these is a real signal that was hidden before. The rest of this article explains the option behind each change.
testpaths: where to look for tests
testpaths = tests tells pytest which directories to search when you run it without paths. It prevents accidental collection from docs, scripts, virtual environments or vendored code, and on big repositories it makes start-up faster because pytest scans less. Passing paths explicitly, such as pytest tests/test_app.py, still works. Keeping your virtual environment outside the project, as in our virtual environment tutorial, avoids another common source of slow collection.
addopts: options added to every run
addopts is inserted into the command line every time, as if you had typed it. We used -ra, which prints a short summary of every outcome except passes (that is why the FAILED lines appeared), and the strict markers flag. Other popular choices are -q or -v for verbosity, a maxfail limit to stop early, -n auto for parallel runs with pytest-xdist, and coverage options. Keep it short: options that only some people want, such as dropping into the debugger, belong on the command line.
markers and strict markers
pytest -q -m "not slow"
2 failed, 1 passed, 1 deselected
# after a typo: @pytest.mark.sloww
ERROR collecting tests/test_app.py
'sloww' not found in `markers` configuration option
The markers option registers custom markers with a description that appears in the markers help listing. Registration lets you select tests, such as -m "not slow" to skip slow ones in a quick local run. With strict markers in addopts, an unregistered marker is an error. Without it, the typo would only produce a warning, and the test you meant to mark as slow would run in every quick run. Markers combine well with fixtures, covered in our pytest fixtures guide.
xfail_strict: catch fixed bugs
@pytest.mark.xfail marks a test that is expected to fail, usually because of a known bug. By default, if such a test starts passing, pytest reports it as xpassed and moves on. With xfail_strict = true, an unexpected pass fails the run, as [XPASS(strict)] known bug showed. That forces someone to remove the stale marker once the bug is fixed, so the test protects against the bug coming back. To check that code raises an error on purpose, use pytest.raises instead of xfail.
filterwarnings: turn warnings into failures
filterwarnings uses the same syntax as Python’s own warning filters: action::Category, optionally with a message pattern and module. error::DeprecationWarning made our deprecated call fail, so you find out about an upcoming breaking change while you still have time to fix it. You can also silence noise from a third-party library with a line such as ignore::DeprecationWarning:somelib.*. Lines lower in the list take precedence over earlier ones.
minversion: require a pytest version
minversion = 8.0 makes pytest stop with an error if an older version is installed, rather than running with options it does not understand. It is a cheap safeguard for teams with many machines. Pinning the version in your requirements file is still the main control.
Which config file wins?
# pyproject.toml added next to pytest.ini
[tool.pytest.ini_options]
testpaths = ["docs"]
pytest
rootdir: /work/proj
configfile: pytest.ini (WARNING: ignoring pytest config in pyproject.toml!)
2 failed, 2 passed
Pytest picks one configuration file; settings from several files are never merged. pytest.ini wins over pyproject.toml, tox.ini and setup.cfg, even if it is empty. In our run, the conflicting testpaths = ["docs"] in pyproject.toml was ignored, and pytest 9.2 printed an explicit warning saying so. The header line configfile: always shows which file was used, so check it first when a setting seems to have no effect.
Pytest also searches upward. When we ran it from inside the tests folder, it still found pytest.ini one level up and produced the same result. That is why the file belongs at the project root.
Tip: pick one place for pytest settings. If your project already uses pyproject.toml for everything, put them there and do not create a pytest.ini at all.
Overriding settings from the command line
pytest -q -o xfail_strict=false -W ignore::DeprecationWarning
3 passed, 1 xpassed
-o name=value overrides any ini option for one run, and -W adds a warning filter. Both are handy when investigating, but do not hide them inside CI scripts, or the config file stops describing what really runs. The -c option points pytest at a different file entirely, and the help output lists every ini option with its description.
Other useful ini options
| Option | What it does |
|---|---|
python_files |
File name patterns to collect, default test_*.py and *_test.py |
python_functions |
Function name prefix, default test |
norecursedirs |
Directories never searched, such as build or .venv |
pythonpath |
Paths added to sys.path, often src |
log_cli, log_cli_level |
Show log records live during the run |
timeout |
Per-test time limit (needs the pytest-timeout plugin) |
required_plugins |
Fail if listed plugins are not installed |
junit_family |
Format of JUnit XML reports for CI systems |
We did not run the options in this table. In a CI pipeline such as our GitHub Actions guide, a committed pytest.ini means the workflow file can simply call pytest. Strict settings also help surface flaky tests sooner, because warnings and unexpected passes no longer slip by.
Final thoughts
A pytest ini file is a few lines of text that make your test suite stricter and more predictable. Start with testpaths, an addopts line with the report summary and strict markers, registered markers, xfail_strict = true and a filterwarnings rule for deprecations. Keep settings in one file, check the configfile: line when something looks wrong, and use overrides only for one-off experiments. In our small project, those few lines exposed three problems that a plain run had hidden.
Frequently asked questions
Where should pytest.ini be placed?
In the project root, next to your tests folder. Pytest searches upward from the current directory, so it finds the file even when you run tests from a subfolder.
What is addopts in pytest.ini?
It lists command-line options that pytest adds to every run, as if you had typed them, for example a report summary flag and strict markers.
Should I use pytest.ini or pyproject.toml?
Either works. Use pyproject.toml if your project already keeps its tool settings there. Avoid having both, because pytest.ini wins and the pyproject.toml settings are ignored.
How do I register custom markers?
Add a markers option with one marker per line and a short description. With strict markers enabled, any unregistered marker then causes a collection error.
How do I override a pytest.ini option for one run?
Use the o option followed by name equals value on the command line, for example to switch xfail_strict off while investigating a failure.
Keep learning
Need help with testing, WordPress or SEO?
We help teams ship better software and grow their sites. Tell us what you are working on and we will suggest a clear next step.