Install & Compatibility
Where this runs
tested against v1.7.0 · 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.410s · 31.2MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.8s · import 0.376s · 32MB
30MB installed
● package 30MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
pytest.mark.flaky
✓ import pytest
@pytest.mark.flaky(retries=3, delay=1)
def test_something_flaky():
# Test implementation
pass
The `pytest.mark.flaky` decorator is the primary way to mark individual tests for retrying. Direct imports from `pytest_retry` itself are generally not needed for basic usage, as pytest discovers the plugin automatically.
Mark a test function with `@pytest.mark.flaky(retries=N, delay=S)` to make it retry N additional times upon failure, with S seconds delay between attempts. Global retry settings can be configured via command-line arguments (`--retries N --retry-delay S`) or in `pytest.ini`/`pyproject.toml`.
import pytest
import random
@pytest.mark.flaky(retries=2, delay=0.5)
def test_sometimes_fails():
# This test has a 50% chance to fail, simulating flakiness.
# It will retry up to 2 times (3 attempts total) with a 0.5-second delay.
if random.random() < 0.5:
pytest.fail("Simulated intermittent failure")
assert True
# To run this test from your terminal:
# pytest your_test_file.py
# You can also set global retries:
# pytest --retries 2 --retry-delay 0.5 your_test_file.py
Debug
Known issues
breakingBehavioral change in `flaky` mark argument fallback in version 1.4.0. Previously, arguments not specified in a `flaky` mark would fall back to default plugin values. From 1.4.0 onwards, unspecified arguments now fall back to your global defaults (e.g., from command line or `pytest.ini`) if specified, before falling back to plugin defaults.fixReview tests using `@pytest.mark.flaky` and ensure explicit `retries` and `delay` arguments are set if global defaults should not apply, or adjust global defaults accordingly.
affects: <1.4.0
gotchaCompatibility issues with `pytest-xdist` could lead to `ResourceWarning` messages, especially when using `n > 1` parallel workers.fixUpgrade to `pytest-retry` version 1.7.0 or higher, which includes a fix for this issue.
affects: <1.7.0
gotchaThere's another popular plugin, `pytest-rerunfailures`, which provides similar functionality but uses different command-line options (`--reruns`, `--reruns-delay`) and decorator arguments (`reruns`, `reruns_delay`). These two plugins are not compatible and should not be installed together.fixChoose either `pytest-retry` or `pytest-rerunfailures` and ensure only one is installed. Use the correct arguments (`retries`, `delay` for `pytest-retry`; `reruns`, `reruns_delay` for `pytest-rerunfailures`) for the chosen plugin.
affects: all
gotchaOlder versions of `pytest-retry` (prior to 1.6.2) had an 'Item instantiation error' when used with `pytest 8`.fixIf using `pytest 8`, ensure `pytest-retry` is at version 1.6.2 or newer.
affects: <1.6.2 (when used with pytest 8)
gotchaWhen using `pytest-retry` with other reporting plugins (e.g., `pytest-html`), the default 'retried' outcome name might cause compatibility issues.fixFrom version 1.7.0, use the `--retry-outcome` command-line option to specify a compatible outcome string (e.g., `pytest --retry-outcome rerun` for `pytest-html`).
affects: <1.7.0
gotchaGlobal configuration of retries and delays via `pytest.ini` or `pyproject.toml` files was introduced in version 1.5.0. Prior versions only supported command-line arguments for global settings.fixFor global configuration using `.ini` or `pyproject.toml`, upgrade to `pytest-retry` version 1.5.0 or newer. For older versions, use command-line arguments like `--retries` and `--retry-delay`.
affects: <1.5.0
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'pytest_retry'
The pytest-retry plugin is either not installed or you are attempting to import it directly in your test file, which is not how pytest plugins are typically used.
fixEnsure the plugin is installed with `pip install pytest-retry` and remove any explicit `import pytest_retry` statements from your test files, as pytest automatically discovers and loads installed plugins.
AttributeError: 'MarkDecorator' object has no attribute 'flaky'
The `@pytest.mark.flaky` decorator is not recognized because the pytest-retry plugin is not installed or not active in your pytest environment.
fixInstall the pytest-retry plugin using `pip install pytest-retry`.
Error: option --retries: invalid int value: 'abc'
The `--retries` command-line option was provided with a value that cannot be converted to an integer.
fixProvide a valid integer for the `--retries` option, for example: `pytest --retries 3`.
TypeError: '<=' not supported between instances of 'str' and 'int'
An incorrect type (e.g., a string instead of an integer) was passed to the `reruns` argument of the `@pytest.mark.flaky` decorator.
fixEnsure that `reruns` receives an integer and `reruns_delay` receives an integer or float, for example: `@pytest.mark.flaky(reruns=3, reruns_delay=1.5)`.
Upgrade
Version history
1.7.0latest on PyPI · released Jan 19, 2025
Audit
Dependencies
pytestrequiredCore testing framework that this plugin extends. Requires pytest>=7.0.0.
pythonrequiredRuntime environment. Requires Python>=3.9.