Pytest Pythonpath Plugin

0.7.4 · maintenance · verified Thu Apr 16

pytest-pythonpath is a pytest plugin designed to extend the `PYTHONPATH` from `pytest.ini` configuration files or command-line arguments before tests run. It provides functionality to add arbitrary directories to `sys.path` for module discovery during test execution. This plugin reached version 0.7.4 in February 2022 and is now largely considered obsolete since `pytest` version 7.0.0 introduced equivalent built-in functionality.

Common errors

```
ModuleNotFoundError: No module named 'your_module'
```
cause Pytest cannot find your application's modules because their containing directories are not on the `PYTHONPATH` during test execution.

fix Ensure your `pytest.ini` includes the path to your module's root directory under `[pytest] pythonpath = your/module/root`. With `pytest >= 7.0.0`, ensure you're using `pytest`'s built-in `pythonpath` option and not relying on the `pytest-pythonpath` plugin.
```
Pytest 7.0.0 appears to break pytest-pythonpath python_paths in pytest.ini
```
cause This specific error message indicates a conflict where `pytest` 7.0.0+ has its own `pythonpath` handling, overriding or clashing with the `pytest-pythonpath` plugin's configuration.

fix Uninstall `pytest-pythonpath` and configure your `pythonpath` directly in `pytest.ini` or `pyproject.toml` using `pytest`'s native `pythonpath` option. For example, `[pytest] pythonpath = .` or `[tool.pytest.ini_options] pythonpath = ["src"]`.

Warnings

breaking The `pytest-pythonpath` plugin is largely obsolete and not recommended for use with `pytest` versions 7.0.0 and later. `pytest` itself now includes a built-in `pythonpath` configuration option that provides the same core functionality, potentially leading to conflicts or ignored configurations if both are used.
Fix: Remove `pytest-pythonpath` from your dependencies (`pip uninstall pytest-pythonpath`). Use the built-in `pytest` configuration in your `pytest.ini`, `pyproject.toml`, or `setup.cfg` (e.g., `[pytest] pythonpath = src`).
gotcha Using `site_dirs` in `pytest.ini` for `pytest-pythonpath` (or its built-in equivalent) processes directories differently than `python_paths`. `site_dirs` uses `site.addsitedir`, which might not place the paths at the very beginning of `sys.path`, potentially causing module resolution order issues if you expect strict precedence.
Fix: Prefer `python_paths` if you need your specified directories to be at the absolute front of `sys.path` to ensure your local modules are found before others. Use `site_dirs` only when `addsitedir` behavior (e.g., `.pth` file processing) is specifically desired.

Install

pip install pytest-pythonpath Install stable version

Quickstart

To configure `pytest-pythonpath`, create or modify your `pytest.ini` file. The `python_paths` option adds directories to the beginning of `sys.path`. The `site_dirs` option processes directories similar to `.pth` files, using `addsitedir`, though these paths might not be at the very front of `sys.path`. Paths are relative to the project's root directory.

[pytest]
python_paths = src my_project/libs
site_dirs = other_packages

view raw JSON →