---
id: pytest-retry
version: "1.7.0"
license: MIT License Copyright (c) 2022 Silas Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the… (full text in the JSON record)
license_treatment: permissive
maintenance: dormant
---

# pytest-retry — Adds the ability to retry flaky tests in CI environments

License: permissive · Maintenance: dormant · Downloads: 2.6M/mo

## 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 above — 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

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

- License: MIT License Copyright (c) 2022 Silas Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the… (full text in the JSON record) (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: dormant
- Downloads: 2.6M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

pytest flaky test retry, test rerun on failure, pytest retry plugin, flaky test handling, retry failed tests pytest, test resilience ci, intermittent test failures, pytest-plugin, ci-resilience, flaky-tests

[View on SkillFed](https://skillfed.io/packages/pytest-retry) · [View on PyPI](https://pypi.org/project/pytest-retry/)