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

Confusion Matrix Explained: Precision, Recall, F1 and Thresholds in Python

Confusion matrix explained with Python: TP, FP, FN, TN, precision, recall, F1, the accuracy trap, threshold choice by cost and…

Read article →
Software Development

API Pagination: Offset vs Cursor vs Keyset, Tested on 1 Million Rows

API pagination explained: offset vs keyset and cursor pagination timed on 1 million rows, duplicates when data changes, the ties…

Read article →
DevOps

Git Submodule Explained: Add, Clone, Update and Remove Safely

Git submodule explained: add, clone, update –init, update –remote, the detached HEAD trap, foreach and clean removal, tested step by…

Read article →
Test Automation

Pytest tmp path Explained: tmp_path, tmp_path_factory and Temp Files

Pytest tmp_path explained: per-test temporary folders, tmp_path_factory for shared files, monkeypatch.chdir, legacy tmpdir, retention and basetemp.

Read article →
Software Testing

Test Case Prioritization: 6 Techniques Compared With APFD

Test case prioritization compared: risk, coverage, cost, history and random orders scored with APFD and time to find all faults…

Read article →
Databases & SQL

Full Text Search in SQL: FTS5, Ranking, Phrases and Speed

Full text search in SQL with SQLite FTS5: MATCH queries, phrases, prefixes, NEAR, stemming, BM25 ranking, snippets, two gotchas and…

Read article →
Databases & SQL

Generated Columns in SQL: Virtual vs Stored, Indexes and Limits

Generated columns in SQL explained: virtual vs stored, automatic updates, write errors, storage cost, indexing, JSON fields and support in…

Read article →
Software Development

Object Freeze in JavaScript: Shallow vs Deep, Seal and const

Object freeze in JavaScript explained: freeze vs seal vs const, strict mode errors, shallow vs deep freeze, frozen arrays, Map…

Read article →
Software Development

Python hashlib: SHA-256, File Hashes, HMAC and Password Hashing

Python hashlib explained: SHA-256 for strings and files, algorithm speeds, why passwords need PBKDF2 or scrypt, safe verification and HMAC…

Read article →
Software Development

Python UUID Explained: uuid1, uuid4, uuid5, uuid7 and Database Keys

Python UUID explained: uuid4, uuid5, uuid1 privacy, time-ordered uuid7, parsing, storage formats and UUIDs as database keys, tested on Python…

Read article →
Artificial Intelligence

Random Forest in Python: Bagging, Feature Sampling and OOB From Scratch

Random forest in Python from scratch: bootstrap sampling, feature sampling, number of trees, out-of-bag evaluation and impurity vs permutation importance.

Read article →
Software Development

MIME Types Explained: Content-Type, nosniff and a Common Types List

MIME types explained and tested in a browser: Content-Type, nosniff, scripts and stylesheets with wrong types, a common MIME types…

Read article →
DevOps

Git Clean Explained: Remove Untracked Files Without Regret

Git clean explained with dry runs: -n, -f, -d, -x, -X, exclusions, paths, nested repositories and interactive mode, plus a…

Read article →
Test Automation

Pytest approx: Comparing Floats With rel, abs and Collections

Pytest approx explained: default tolerances, the near-zero trap, rel and abs, lists and dicts, NaN, NumPy, and how it differs…

Read article →
Software Testing

Accessibility Testing: WCAG Checklist, Automated Tools and Manual Checks

Accessibility testing explained: WCAG basics, an axe-core scan of a broken and a fixed page, what automation missed, contrast checks…

Read article →
Databases & SQL

SQL UNPIVOT: Turn Columns Into Rows, 4 Ways Tested

SQL UNPIVOT explained: turn columns into rows with UNION ALL, CROSS JOIN with CASE, JSON functions or native UNPIVOT, with…

Read article →
Software Development

Intl NumberFormat in JavaScript: Currency, Compact, Percent and Units

Intl.NumberFormat in JavaScript: locales, currency, compact notation, percent, units, rounding, formatToParts, the non-breaking space trap and formatter reuse.

Read article →
Databases & SQL

SQL EXPLAIN Plan: How to Read Query Plans and Fix Slow Queries

SQL EXPLAIN plan explained: read scans, index searches, covering indexes and temporary sorts, with before and after timings for five…

Read article →
Artificial Intelligence

Decision Tree in Python: Gini, Entropy and Overfitting From Scratch

Decision tree in Python from scratch: Gini impurity, entropy, information gain, best splits, readable rules, and how depth and leaf…

Read article →
DevOps

Git Blame Explained: Find Who Changed a Line, and Why

Git blame explained with a real repository: ignore whitespace, line ranges and functions, ignore-revs files for formatting commits, moved code…

Read article →
Test Automation

Pytest Benchmark: Measure Speed and Catch Performance Regressions

Pytest benchmark tutorial: the benchmark fixture, reading results, parametrized and pedantic benchmarks, saving baselines and failing the build on regressions.

Read article →
Software Testing

Defect Density: Formula, Worked Examples and How to Use It

Defect density explained: the formula, a five-module worked example, per KLOC vs per function point, severity weighting, defect removal efficiency…

Read article →
Databases & SQL

Case Insensitive Search in SQL: LOWER, LIKE, COLLATE and Indexes

Case insensitive search in SQL: LOWER, LIKE, COLLATE NOCASE and expression indexes compared with query plans, plus accented letters and…

Read article →
Databases & SQL

ON DELETE CASCADE in SQL: CASCADE vs SET NULL vs RESTRICT

ON DELETE CASCADE in SQL tested: CASCADE vs SET NULL vs RESTRICT, multi-level cascades, the SQLite foreign key pragma, row…

Read article →
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 →
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 →
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 →
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 →
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 →