pytest-rerunfailures
raw JSON → 16.1 verified Tue May 12 auth: no python install: verified quickstart: verified
pytest-rerunfailures is a plugin for pytest that re-runs failed or intermittently failing tests to eliminate flaky failures, improving the reliability of CI/CD pipelines. It is actively maintained with frequent releases, typically every few months, adding new features and ensuring compatibility with the latest Python and pytest versions.
pip install pytest-rerunfailures Warnings
breaking Dropped support for older Python and pytest versions in recent releases. Version 16.1 requires Python 3.10+, and version 16.0 requires pytest 8.0+. ↓
fix Upgrade your Python environment to 3.10+ and pytest to 8.0+ before upgrading to `pytest-rerunfailures` 16.0 or newer.
gotcha Incompatible with `pytest-xdist`'s `--looponfail` flag, `pytest`'s core `--pdb` flag, and the `flaky` plugin. Do not use `pytest-rerunfailures` simultaneously with these. Also, explicitly incompatible with `pytest-rerunclassfailures`. ↓
fix Choose one rerun/flakiness plugin or strategy. If using `pytest-xdist`, ensure you are not using `--looponfail`. Avoid using `--pdb` with reruns.
gotcha The order of precedence for setting rerun counts is: `@pytest.mark.flaky()` decorator > command-line `--reruns` option > `pytest.ini`/`pyproject.toml` configuration. The `--force-reruns` command-line option can override all other settings. ↓
fix Be mindful of where you define your rerun counts. If you find unexpected rerun behavior, check if a higher-priority setting is overriding your intended configuration.
gotcha Recovery from hard crashes (e.g., segfaults) using `pytest-xdist` (via the `-n` flag) requires `pytest-xdist >= 2.3.0` and assumes workers and controller are on the same local area network (LAN). This functionality may not operate if this assumption is not met. ↓
fix Ensure `pytest-xdist` is updated to a compatible version and that your test execution environment for parallel runs aligns with the LAN assumption for crash recovery.
gotcha When a teardown function fails, `pytest-rerunfailures` will generate two reports: one for the test case itself and another for the teardown error. This can sometimes be confusing in the test output. ↓
fix Be aware of this reporting behavior when debugging tests where teardown issues might occur. The separate reports help pinpoint whether the failure was in the test logic or the cleanup.
gotcha Running pip as the 'root' user can lead to broken permissions and system instability. It is strongly recommended to use a virtual environment or run pip as a non-root user. Additionally, there are notices about available pip updates. ↓
fix Use a Python virtual environment (e.g., `venv`) for package management. If operating within a containerized environment where root is unavoidable, consider using `--root-user-action=ignore` if you understand the implications, or switch to a non-root user. Regularly update pip using `pip install --upgrade pip`.
Install compatibility verified last tested: 2026-05-12
python os / libc status wheel install import disk
3.10 alpine (musl) wheel - 0.46s 30.7M
3.10 alpine (musl) - - 0.46s 30.5M
3.10 slim (glibc) wheel 2.7s 0.30s 31M
3.10 slim (glibc) - - 0.30s 31M
3.11 alpine (musl) wheel - 0.56s 33.6M
3.11 alpine (musl) - - 0.64s 33.4M
3.11 slim (glibc) wheel 2.6s 0.51s 34M
3.11 slim (glibc) - - 0.54s 34M
3.12 alpine (musl) wheel - 0.53s 25.2M
3.12 alpine (musl) - - 0.53s 25.0M
3.12 slim (glibc) wheel 2.5s 0.51s 26M
3.12 slim (glibc) - - 0.50s 26M
3.13 alpine (musl) wheel - 0.46s 25.0M
3.13 alpine (musl) - - 0.46s 24.7M
3.13 slim (glibc) wheel 2.5s 0.43s 26M
3.13 slim (glibc) - - 0.44s 25M
3.9 alpine (musl) wheel - 0.38s 30.0M
3.9 alpine (musl) - - 0.38s 29.8M
3.9 slim (glibc) wheel 3.1s 0.32s 31M
3.9 slim (glibc) - - 0.31s 30M
Imports
- pytest
import pytest
Quickstart verified last tested: 2026-04-24
import pytest
import random
def test_flaky_example():
# This test will randomly fail, demonstrating rerunfailures
if random.choice([True, False, False]): # Higher chance to fail initially
pytest.fail("Simulated flaky failure")
# To run with reruns: pytest --reruns 3 your_test_file.py
# To mark a specific test as flaky:
@pytest.mark.flaky(reruns=2, reruns_delay=1)
def test_another_flaky_example():
if random.choice([True, False]):
pytest.fail("Another flaky failure")
# Example of pytest.ini configuration (add to a file named pytest.ini in your project root):
# [pytest]
# reruns = 2
# reruns_delay = 1
# You can then run: pytest