How to Use setup.cfg for pytest Configuration

You can configure pytest options by adding a [tool:pytest] section in your setup.cfg file. This lets you set test paths, markers, and other settings without command-line arguments or pytest.ini files.

Syntax

The setup.cfg file uses an INI-style format. To configure pytest, add a [tool:pytest] section. Inside this section, you list pytest options as key-value pairs.

Common keys include addopts for extra command-line options, testpaths for test directories, and markers to register custom markers.

ini

[tool:pytest]
addopts = -v --maxfail=2
testpaths = tests
markers =
    slow: marks tests as slow
    smoke: marks smoke tests

Example

This example shows a setup.cfg file configuring pytest to run tests in the tests folder, show verbose output, stop after 2 failures, and register two custom markers.

Run pytest in the terminal, and it will use these settings automatically.

ini

[tool:pytest]
addopts = -v --maxfail=2
testpaths = tests
markers =
    slow: marks tests as slow
    smoke: marks smoke tests

Output

============================= test session starts ==============================
collected 5 items

tests/test_example.py::test_fast PASSED                                  [ 20%]
tests/test_example.py::test_slow SKIPPED (marked slow)                   [ 40%]
tests/test_example.py::test_smoke PASSED                                [ 60%]
tests/test_example.py::test_fail FAILED                                [ 80%]
tests/test_example.py::test_another_fail FAILED                        [100%]

=========================== short test summary info ===========================
FAILED tests/test_example.py::test_fail
FAILED tests/test_example.py::test_another_fail
========================= 2 failed, 2 passed, 1 skipped in 0.12s =================

Common Pitfalls

One common mistake is using [pytest] instead of [tool:pytest] in setup.cfg. pytest only recognizes the [tool:pytest] section there.

Another issue is incorrect indentation or missing newlines in the markers list, which can cause pytest to ignore marker registrations.

Also, avoid placing setup.cfg in the wrong directory; it must be in the root folder of your project.

ini

[pytest]
addopts = -v

# WRONG: pytest ignores this section in setup.cfg

[tool:pytest]
addopts = -v

# CORRECT: pytest reads this section

Quick Reference

Option	Description	Example
addopts	Extra command-line options for pytest	addopts = -v --maxfail=1
testpaths	Directories where pytest looks for tests	testpaths = tests src/tests
markers	Register custom markers with descriptions	markers = slow: marks slow tests smoke: marks smoke tests
python_files	Glob pattern for test file names	python_files = test_*.py *_test.py
python_classes	Test class name patterns	python_classes = Test*
python_functions	Test function name patterns	python_functions = test_*

Key Takeaways

Use the [tool:pytest] section in setup.cfg to configure pytest options.

List options as key-value pairs like addopts, testpaths, and markers.

Ensure setup.cfg is in your project root for pytest to find it.

Avoid using [pytest] section in setup.cfg; it is ignored by pytest.

Properly format markers and options to prevent pytest ignoring them.