1. Home
  2. Blog
  3. Test Automation

Test Automation

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.

9 min read
Pytest ini explained: addopts, markers, testpaths and precedence

Key takeaways

  • A pytest ini file is a [pytest] section in pytest.ini at 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.sloww stopped 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

Work with Stack Quora

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.

Keep reading

More guides on testing, AI & modern development

Enjoyed this article? Pick a topic and jump straight into our newest tutorials.

Artificial Intelligence

Logistic Regression in Python: Sigmoid, Log Loss and Gradient Descent From Scratch

Logistic regression in Python from scratch: sigmoid, log loss, gradient descent, odds ratios, thresholds, sigmoid overflow and separable data, tested…

Read article →
Software Development

Content Security Policy Explained: Nonces, strict-dynamic and Report-Only

Content security policy explained: nonces, strict-dynamic, Report-Only, eval, image and style rules, tested in a real browser, plus a strict…

Read article →
DevOps

Git Worktree Explained: Work on Two Branches at Once

Git worktree explained: add, list, remove, prune, lock and detached worktrees, a hotfix workflow, and the errors you will hit,…

Read article →
Test Automation

Pytest ini Explained: addopts, markers, testpaths and Precedence

Pytest ini explained: testpaths, addopts, strict markers, xfail_strict, filterwarnings, minversion, config file precedence and command-line overrides, tested.

Read article →
Software Testing

Test Estimation Techniques: WBS, Three Point PERT and Monte Carlo

Test estimation techniques worked through: WBS, three point PERT, total uncertainty, a Monte Carlo check, percentage rules and Wideband Delphi.

Read article →
Databases & SQL

Gaps and Islands in SQL: Find Streaks and Missing Ranges

Gaps and islands in SQL: find login streaks and missing ranges with ROW_NUMBER, DENSE_RANK, LAG and LEAD, plus the duplicate…

Read article →
Databases & SQL

INSERT INTO SELECT in SQL: Copy Rows Between Tables Safely

INSERT INTO SELECT in SQL: copy rows between tables with chosen columns, joins and summaries, avoid duplicates on reruns, upsert,…

Read article →
Software Development

JavaScript Proxy Explained: All 13 Traps, Reflect and Real Use Cases

JavaScript Proxy explained: all 13 traps, Reflect, validation, defaults, hidden keys, revocable proxies, private field problems and the speed cost,…

Read article →
Software Development

Python Threading Explained: Threads, Locks, Queues and the GIL, Timed

Python threading explained and timed: threads vs processes, the GIL, a real race condition, locks, ThreadPoolExecutor, queues, events and daemon…

Read article →
Software Development

Python Match Case: 12 Pattern Matching Examples, Guards and Traps

Python match case explained with 12 tested examples: literals, OR patterns, guards, sequences, dictionaries, classes, the capture trap and speed…

Read article →
Artificial Intelligence

Linear Regression in Python: Least Squares From Scratch, With R Squared

Linear regression in Python from scratch: closed form, NumPy least squares and gradient descent, R squared, RMSE, outliers and curved…

Read article →
Software Development

301 vs 302 Redirect: Differences, SEO Impact, 307 and 308

301 vs 302 redirect: the differences, SEO impact, 307 and 308, method changes, redirect chains and loops, all tested on…

Read article →
DevOps

Git Remote Explained: Add, Set-URL, Rename, Remove and Push URLs

Git remote explained: add, set-url, separate push URLs, rename, remove and prune, plus how to avoid leaking tokens in remote…

Read article →
Test Automation

Pytest Mock: mocker.patch, spy, side_effect and autospec Explained

Pytest mock explained: mocker.patch, return_value, side_effect, spy, autospec and PropertyMock, with tested examples for APIs, clocks and retries.

Read article →
Software Testing

System Testing Explained: Types, Process and a Real End-to-End Example

System testing explained: types, entry and exit criteria, the process, and a real end-to-end test suite run against a small…

Read article →
Databases & SQL

SQL Random Rows: How to Select Random Rows Fast and Fairly

SQL random rows: how to select random rows fast and fairly, timing ORDER BY RANDOM, offsets and ID jumps, and…

Read article →
Databases & SQL

SQL Median: 4 Ways to Calculate the Median, With Tested Queries

SQL median explained: four tested ways to calculate the median, including percentile functions, window ranks, offsets and per group medians.

Read article →
Software Development

JavaScript Regex Explained: Patterns, Flags, Groups and Pitfalls

JavaScript regex explained: literals, flags, groups, named groups, lookarounds, matchAll, replace and the catastrophic backtracking trap, tested in Node.

Read article →
Artificial Intelligence

Naive Bayes Classifier Explained: Build a Spam Filter in Python

Naive Bayes classifier explained by building a spam filter in Python: Bayes rule, the naive assumption, Laplace smoothing, log probabilities…

Read article →
DevOps

Git Branch Explained: Create, Switch, Rename, Delete and Recover

Git branch explained with tested commands: list, create, switch, rename, delete, merged checks, recovering deleted branches, remote tracking and naming.

Read article →
Test Automation

Pytest raises: Testing Exceptions, match and excinfo

Pytest raises explained with tested examples: match regexes, excinfo, custom and chained exceptions, parametrized error cases, pytest.warns and common mistakes.

Read article →
Software Testing

Non Functional Testing: Types, Metrics and a Real Load Test

Non functional testing explained: 10 key types, measurable requirements, latency percentiles and what a small real load test revealed about…

Read article →
Databases & SQL

SQL ROUND Function: Decimals, Ties, CEIL, FLOOR and Money

SQL ROUND explained with tested queries: decimals, tie rules, the 2.675 float trap, negative digits, CEIL, FLOOR, truncation and rounding…

Read article →
Databases & SQL

Recursive CTE in SQL: Hierarchies, Paths, Series and Cycles

Recursive CTE in SQL explained with tested queries: org charts with levels and paths, walking up a tree, team sizes,…

Read article →
Artificial Intelligence

K Means Clustering Explained: How It Works, With Python Code

K means clustering explained: the algorithm, a from-scratch NumPy version, choosing k with the elbow and silhouette methods, k-means++, scaling…

Read article →
DevOps

Git Log Explained: 15 Useful Commands and Pretty Formats

Git log explained with 15 tested commands: oneline, graph, filters by author, date, message and code, file history, stats, pretty…

Read article →
Test Automation

Pytest conftest.py Explained: Shared Fixtures, Hooks and Overrides

Pytest conftest.py explained with a tested suite: shared fixtures, scope and teardown, folder overrides, autouse, custom options, markers and useful…

Read article →
Software Testing

Usability Testing: Methods, Metrics, SUS Score and Checklist

Usability testing explained: methods, planning, writing tasks, running sessions, metrics, SUS scoring, how many users you need and a practical…

Read article →
Artificial Intelligence

K Nearest Neighbors (KNN) Explained: How It Works, With Python Code

K nearest neighbors explained: the KNN algorithm, a from-scratch NumPy version, choosing k, feature scaling, distance metrics, regression and vector…

Read article →
DevOps

Git Rebase Interactive: Squash, Fixup, Reword and Autosquash

Git rebase interactive explained step by step: pick, reword, squash, fixup, edit, drop, autosquash, conflicts and undoing a rebase with…

Read article →
Software Testing

Alpha vs Beta Testing: Key Differences, Exit Criteria and Checklist

Alpha vs beta testing compared: who tests, what each phase finds, entry and exit criteria, how to run a beta,…

Read article →
Test Automation

Pytest Monkeypatch: 10 Tested Examples for Env Vars, Time and APIs

Pytest monkeypatch explained with 10 passing tests: environment variables, functions, config, time, sleeps, paths, blocking the network and the wrong-target…

Read article →
Artificial Intelligence

Softmax Function Explained: Formula, Python Code and Stable Version

The softmax function explained: formula, worked example, NumPy code, the stable version that avoids NaN, temperature, cross-entropy and softmax vs…

Read article →
DevOps

Git Diff Explained: Staged Changes, Branches and Commits

Git diff explained: read the output, compare unstaged and staged changes, commits and branches, two dots vs three dots, and…

Read article →
Test Automation

Pytest Xdist: Run Tests in Parallel and Cut Test Time

Run pytest tests in parallel with pytest-xdist: install, the -n option, distribution modes, real timings and how to fix shared-state…

Read article →
Software Testing

Verification vs Validation in Software Testing: Example and Table

Verification vs validation in software testing explained with a comparison table and a tested coupon example where every spec test…

Read article →