pytest-retry

What it is and what it does

pytest-retry extends pytest with the ability to automatically re-run tests that fail, addressing the problem of flaky tests that pass inconsistently due to timing issues, external service delays, or environment race conditions. It works as a pytest plugin with two main modes: global retry settings applied to all tests via command-line flags (--retries, --retry-delay) or configuration files, and per-test control via the @pytest.mark.flaky decorator for fine-grained retry policies.

The plugin integrates into pytest's reporting flow to track and display retried tests separately. It supports exception filtering (retry only on specific exceptions or exclude certain ones), configurable timing methods (overwrite vs. cumulative), and custom outcome labels for compatibility with other reporting tools. Teardown steps run after each failed attempt to ensure clean state before retries, though fixture setup itself is not retried. The package is designed as a pragmatic short-term solution while permanent fixes are implemented, not a substitute for addressing root causes of flakiness.

Use it for:

• Retry all tests in a CI pipeline up to N times to reduce false negatives from transient environment issues.
• Mark specific tests known to be flaky with @pytest.mark.flaky to retry only those without affecting the full suite.
• Retry tests only when they fail with specific exceptions (e.g., network timeouts) while failing immediately on assertion errors.
• Add delays between retry attempts to allow intermittent services or resources to recover.
• Generate detailed reports of which tests were retried and why, to identify candidates for permanent fixes.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

pytest-retry is a pytest plugin that automatically retries failed tests, with configurable retry counts, delays, and exception filtering to help manage flaky tests in CI environments.

Yes, if you have flaky tests in CI and need a quick way to reduce false failures while you investigate root causes. The low install friction, permissive license, and absence of known vulnerabilities make it safe to add. Maintenance is dormant but recent, and the plugin's scope is narrow enough that stability is likely. Not recommended as a permanent solution—use it to buy time while fixing the underlying test or environment issues.

Install

pytest-retry on PyPI

pip install pytest-retry

uv add pytest-retry

poetry add pytest-retry

Installing pytest-retry

Before you install

Low friction install with a single runtime dependency on pytest. Maintenance is dormant but the package has received updates as recently as 2025-01-19, and no known vulnerabilities are recorded.

License in practice

MIT License permits use, modification, and distribution with minimal restrictions, making it safe for both open-source and commercial projects.

Quickstart

pip install pytest-retry

# In conftest.py or test file:
import pytest

@pytest.mark.flaky(retries=2, delay=1)
def test_unreliable_service():
    pass

# Or run globally:
# pytest --retries 2 --retry-delay 1

Requires Python 3.9+ and pytest 7.0.0+.

Verify before relying

• Whether the plugin's dormant maintenance status indicates sufficient ongoing support for production use.
• Performance impact of re-running class and module fixtures on large test suites.
• Compatibility with pytest plugins beyond pytest-html when using custom retry-outcome values.

Package facts

Evidence: pytest_retry-1.7.0-py3-none-any.whl

Keywords: rerun, pytest, flaky

Tags

More Testing packages