pytest-dev/pytest · error · ValueError

pytester_example_dir is unset, can't copy examples

Error message

pytester_example_dir is unset, can't copy examples

What it means

Raised by Pytester.copy_example when the ini option 'pytester_example_dir' is not configured. copy_example copies reference example files from a project-local directory into the test's temp dir, and that source directory is declared via pytester_example_dir in your pytest configuration. Without it there is no root from which to resolve examples.

Source

Thrown at src/_pytest/pytester.py:958

        gets recognised as a Python package.
        """
        p = self.path / name
        p.mkdir()
        p.joinpath("__init__.py").touch()
        return p

    def copy_example(self, name: str | None = None) -> Path:
        """Copy file from project's directory into the testdir.

        :param name:
            The name of the file to copy.
        :return:
            Path to the copied directory (inside ``self.path``).
        :rtype: pathlib.Path
        """
        example_dir_ = self._request.config.getini("pytester_example_dir")
        if example_dir_ is None:
            raise ValueError("pytester_example_dir is unset, can't copy examples")
        example_dir: Path = self._request.config.rootpath / example_dir_

        for extra_element in self._request.node.iter_markers("pytester_example_path"):
            assert extra_element.args
            example_dir = example_dir.joinpath(*extra_element.args)

        if name is None:
            func_name = self._name
            maybe_dir = example_dir / func_name
            maybe_file = example_dir / (func_name + ".py")

            if maybe_dir.is_dir():
                example_path = maybe_dir
            elif maybe_file.is_file():
                example_path = maybe_file
            else:
                raise LookupError(
                    f"{func_name} can't be found as module or package in {example_dir}"

View on GitHub (pinned to 98b357f69e)

Solutions

1. Add 'pytester_example_dir = examples' (or your chosen dir) under [tool.pytest.ini_options] in pyproject.toml.
2. Create the referenced examples directory at the repository root (relative to rootpath).
3. Use the pytester_example_path marker to point at a subdirectory if examples live deeper.

Example fix

// before (pyproject.toml)
[tool.pytest.ini_options]
# missing pytester_example_dir
// after
[tool.pytest.ini_options]
pytester_example_dir = "examples"

from pathlib import Path
import pytest

def get_example_dir(config) -> Path | None:
    d = config.getini("pytester_example_dir")
    return Path(config.rootpath / d) if d else None

# in a test
if get_example_dir(pytestconfig) is None:
    pytest.skip("set pytester_example_dir to use copy_example")

try:
    pytester.copy_example("foo.py")
except ValueError:
    pytest.skip("pytester_example_dir not configured")

When it happens

Trigger: Calling pytester.copy_example() in a test without having set pytester_example_dir in pyproject.toml's [tool.pytest.ini_options], pytest.ini, or tox.ini.

Common situations: Using the pytester fixture's example-copying feature for the first time; a CI config that uses a different ini file than the dev machine; migrating config and dropping the option.

Related errors

• {func_name} can't be found as module or package in {example_
• example "{example_path}" is not found as a file or directory
• Unrecognized runpytest option: {self._method}
• could not find test report matching {inamepart!r}: no test r
• found 2 or more testreports matching {inamepart!r}: {values}

AI-assisted analysis of pytest-dev/pytest@98b357f69e (2026-08-04). Data as JSON: /data/errors/26e09bd019fc271b.json. Report an issue: GitHub.