pytest-dev/pytest · error · ValueError

tmp_path_retention_count must be >= 0. Current input: {count

Error message

tmp_path_retention_count must be >= 0. Current input: {count}.

What it means

Raised by TempPathFactory.from_config during pytest_configure if the ini option tmp_path_retention_count parses to a negative integer. The option controls how many recent tmp_path session directories pytest keeps around; a negative value is meaningless and is rejected eagerly so later cleanup logic (which indexes by count) does not break.

Source

Thrown at src/_pytest/tmpdir.py:97

        # Register cleanups for session finish. Also called atexit as a last
        # resort if sessionfinish for some reason doesn't happen.
        self._exit_stack = ExitStack()

    @classmethod
    def from_config(
        cls,
        config: Config,
        *,
        _ispytest: bool = False,
    ) -> TempPathFactory:
        """Create a factory according to pytest configuration.

        :meta private:
        """
        check_ispytest(_ispytest)
        count = int(config.getini("tmp_path_retention_count"))
        if count < 0:
            raise ValueError(
                f"tmp_path_retention_count must be >= 0. Current input: {count}."
            )

        policy: RetentionType = config.getini("tmp_path_retention_policy")

        return cls(
            given_basetemp=config.option.basetemp,
            trace=config.trace.get("tmpdir"),
            retention_count=count,
            retention_policy=policy,
            _ispytest=True,
        )

    def _ensure_relative_to_basetemp(self, basename: str) -> str:
        basename = os.path.normpath(basename)
        if (self.getbasetemp() / basename).resolve().parent != self.getbasetemp():
            raise ValueError(f"{basename} is not a normalized and relative path")
        return basename

View on GitHub (pinned to 98b357f69e)

Solutions

1. Set tmp_path_retention_count to 0 or a positive integer (default is 3).
2. If the intent is 'do not keep anything', use tmp_path_retention_policy = none instead of a negative count.
3. Search all ini sources (pytest.ini, pyproject.toml, tox.ini, setup.cfg, CLI --override-ini) for tmp_path_retention_count.

Example fix

// before (pytest.ini)
[pytest]
tmp_path_retention_count = -1

// after
[pytest]
tmp_path_retention_count = 0
tmp_path_retention_policy = none

def validate_retention_count(config_value):
    n = int(config_value)
    if n < 0:
        raise ValueError(f"tmp_path_retention_count must be >= 0, got {n}")
    return n

def is_valid_retention_count(v) -> bool:
    try:
        return int(v) >= 0
    except (TypeError, ValueError):
        return False

When it happens

Trigger: Setting tmp_path_retention_count = -1 (or any negative) in pytest.ini, pyproject.toml [tool.pytest.ini_options], tox.ini, or setup.cfg, then starting pytest. The check runs at configure time, so the failure happens before any test executes.

Common situations: Confusing retention_count with retention_policy (setting -1 meaning 'none'); copy-pasted config from a blog post; intending 'never delete' and using a negative number instead of a large positive one.

Related errors

• unknown configuration value: {name!r}
• {self.inipath}: config option '{name}' expects one of {_ini_
• {self.inipath}: config option '{name}' expects a string, got
• {self.inipath}: config option '{name}' expects one of {_ini_
• Expected an int string for option {name} of type integer, bu

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