Install & Compatibility
Where this runs
tested against v16.6 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.422s · 31.2MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.7s · import 0.386s · 32MB
30MB installed
● package 30MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
pytest
✓ import pytest
Used for marking tests as flaky via `@pytest.mark.flaky()`. The plugin itself is activated via pytest's discovery mechanism, not direct imports.
To enable `pytest-rerunfailures`, simply install it. You can configure reruns via command-line options (`pytest --reruns N`), a `pytest.mark.flaky` decorator on individual tests, or globally in `pytest.ini`/`pyproject.toml`. Adding `--reruns-delay N` introduces a pause between retries.
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
Debug
Known issues
breakingDropped 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+.fixUpgrade your Python environment to 3.10+ and pytest to 8.0+ before upgrading to `pytest-rerunfailures` 16.0 or newer.
affects: 16.0, 16.1
gotchaIncompatible 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`.fixChoose one rerun/flakiness plugin or strategy. If using `pytest-xdist`, ensure you are not using `--looponfail`. Avoid using `--pdb` with reruns.
affects: All versions
gotchaThe 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.fixBe 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.
affects: All versions
gotchaRecovery 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.fixEnsure `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.
affects: 10.2 and newer
gotchaWhen 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.fixBe 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.
affects: All versions
gotchaRunning 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.fixUse 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`.
affects: pip: All versions when run as root
Upgrade
Version history
16.6latest on PyPI · released Aug 17, 2026
Audit
Dependencies
pytestrequiredCore testing framework, required dependency.
pythonrequiredRequired Python version.
pytest-xdistoptionalOptional: Enables recovery from hard crashes (e.g., segfaults) when running tests in parallel with -n.