Introduction

conftest.py is Pytest’s local configuration and fixture-sharing mechanism. It lets you define reusable fixtures, hooks, and test behavior for a directory tree without forcing every test module to import a central helper module manually.

Why conftest.py Exists

As a test suite grows, certain setup patterns repeat:

• creating a test client
• preparing database fixtures
• defining custom command-line options
• registering hooks that tweak collection or reporting

You could put all of that in ordinary Python files and import it everywhere, but that becomes noisy and easy to forget. Pytest solves the problem by auto-discovering conftest.py files based on directory location.

That means tests can simply request a fixture by name, and Pytest finds it through the fixture-discovery rules.

Fixture Sharing by Directory Scope

A conftest.py file applies to tests in its own directory and subdirectories. That makes it ideal for organizing shared test behavior hierarchically.

A simple example looks like this:

1# tests/conftest.py
2import pytest
3
4
5@pytest.fixture
6def sample_user():
7    return {"id": 1, "name": "Ada"}

Then any test under tests/ can use that fixture without importing it.

# tests/test_users.py
def test_user_name(sample_user):
    assert sample_user["name"] == "Ada"

That “no import required” behavior is the main reason conftest.py feels special.

More Than Fixtures

conftest.py is not just for fixtures. It can also define Pytest hooks and custom command-line options.

For example, you can add a flag that controls whether slow tests run.

# tests/conftest.py
def pytest_addoption(parser):
    parser.addoption("--runslow", action="store_true", default=False)

Then a hook can mark or skip tests based on that option.

1# tests/conftest.py
2import pytest
3
4
5def pytest_collection_modifyitems(config, items):
6    if config.getoption("--runslow"):
7        return
8
9    skip_slow = pytest.mark.skip(reason="need --runslow option to run")
10    for item in items:
11        if "slow" in item.keywords:
12            item.add_marker(skip_slow)

This keeps test behavior close to the tests it affects.

When To Use conftest.py Versus a Plugin

A good rule is:

• use conftest.py for local test-suite behavior tied to a project or subtree
• use a Pytest plugin when the behavior is reusable across many repositories

If the fixture only matters to one application’s tests, conftest.py is the natural home. If the feature is generic enough to publish or share broadly, a plugin is usually cleaner.

This distinction keeps conftest.py from becoming a dumping ground for every test utility the project has ever accumulated.

Organizing Large Test Suites

Large projects often use multiple conftest.py files. A top-level file can define cross-project fixtures, while deeper directories add fixtures specific to API tests, database tests, or UI tests.

For example:

• 'tests/conftest.py for shared clients and global options'
• 'tests/api/conftest.py for HTTP-specific fixtures'
• 'tests/db/conftest.py for database setup'

That structure works well because Pytest resolves fixtures according to directory scope and normal fixture lookup rules.

Common Pitfalls

The most common mistake is putting unrelated business logic into conftest.py. It should support the tests, not become a miscellaneous utilities module.

Another common issue is defining fixtures too broadly. A fixture placed high in the tree becomes visible to many tests, which can create naming collisions or accidental coupling.

Developers also sometimes try to import conftest.py directly from application code. That is usually the wrong design. conftest.py is for Pytest’s discovery system, not for general-purpose imports.

Finally, if fixture behavior becomes hard to trace, the problem is often scope and organization rather than Pytest itself. Split large files into clearer layers and move generic behavior into helper modules or plugins when appropriate.

Summary

• 'conftest.py is Pytest’s directory-scoped place for shared fixtures, hooks, and test configuration.'
• Tests under that directory tree can use its fixtures without explicit imports.
• It is useful for local test behavior such as clients, database setup, and command-line options.
• Use plugins for broadly reusable behavior and keep conftest.py focused on project-specific testing needs.
• Organize multiple conftest.py files by directory when the test suite grows.