Requirements

You will need the following prerequisites in order to use pytest-rerunfailures:

• Python 3.10+ or PyPy3

• pytest 8.2 or newer

This plugin can recover from a hard crash with the following optional prerequisites:

• pytest-xdist 2.3.0 or newer

This package is currently tested against the last 5 minor pytest releases. In case you work with an older version of pytest you should consider updating or use one of the earlier versions of this package.

Installation

To install pytest-rerunfailures:

$ pip install pytest-rerunfailures

Recover from hard crashes

If one or more tests trigger a hard crash (for example: segfault), this plugin will ordinarily be unable to rerun the test. However, if a compatible version of pytest-xdist is installed, and the tests are run within pytest-xdist using the -n flag, this plugin will be able to rerun crashed tests, assuming the workers and controller are on the same LAN (this assumption is valid for almost all cases because most of the time the workers and controller are on the same computer). If this assumption is not the case, then this functionality may not operate.

Re-run all failures

To re-run all test failures, use the --reruns command line option with the maximum number of times you’d like the tests to run:

$ pytest --reruns 5

Failed fixture or setup_class will also be re-executed.

To add a delay time between re-runs use the --reruns-delay command line option with the amount of seconds that you would like wait before the next test re-run is launched:

$ pytest --reruns 5 --reruns-delay 1

To grow the delay after every attempt (exponential backoff), use the --reruns-delay-backoff-factor option. The delay before the n-th re-run is reruns_delay * reruns_delay_backoff_factor ** (n - 1). The default factor is 1.0, which keeps the delay constant. For example, the following waits 1, 2 and 4 seconds before the three re-runs:

$ pytest --reruns 3 --reruns-delay 1 --reruns-delay-backoff-factor 2

Re-run all failures matching certain expressions

To re-run only those failures that match a certain list of expressions, use the --only-rerun flag and pass it a regular expression. For example, the following would only rerun those errors that match AssertionError:

$ pytest --reruns 5 --only-rerun AssertionError

Passing the flag multiple times accumulates the arguments, so the following would only rerun those errors that match AssertionError or ValueError:

$ pytest --reruns 5 --only-rerun AssertionError --only-rerun ValueError

The same matching is applied to each exception in the __cause__ / __context__ chain, so a wrapped error such as raise RuntimeError(...) from MemoryError(...) is still rerun by --only-rerun MemoryError.

The default list can also live in the pytest.ini (or pyproject.toml) file, one expression per line:

[pytest]
only_rerun =
    AssertionError
    ValueError

A --only-rerun flag on the command line replaces the ini list rather than accumulating with it.

Re-run all failures other than matching certain expressions

To re-run only those failures that do not match a certain list of expressions, use the --rerun-except flag and pass it a regular expression. For example, the following would only rerun errors other than that match AssertionError:

$ pytest --reruns 5 --rerun-except AssertionError

Passing the flag multiple times accumulates the arguments, so the following would only rerun those errors that does not match with AssertionError or OSError:

$ pytest --reruns 5 --rerun-except AssertionError --rerun-except OSError

Matching for --rerun-except follows explicit __cause__ links (raise ... from ...), so raise RuntimeError(...) from ValueError(...) is excluded by --rerun-except ValueError. Implicit __context__ from except / finally is not walked, so a ConnectionError raised inside except AssertionError is still rerun by --rerun-except AssertionError.

The exclusion list can also live in the pytest.ini (or pyproject.toml) file as rerun_except, one expression per line.

Exclude test paths from re-runs

To exclude a test file or all tests under a directory from re-runs, use the --rerun-exclude-path option. Relative paths are interpreted relative to pytest’s root directory:

$ pytest --reruns 3 --rerun-exclude-path docs

The option may be passed multiple times to exclude multiple paths.

Re-run individual failures

To mark individual tests as flaky, and have them automatically re-run when they fail, add the flaky mark with the maximum number of times you’d like the test to run:

@pytest.mark.flaky(reruns=5)
def test_example():
    import random
    assert random.choice([True, False])

Note that when teardown fails, two reports are generated for the case, one for the test case and the other for the teardown error.

You can also specify the re-run delay time in the marker, as well as the backoff factor for an exponential backoff:

@pytest.mark.flaky(reruns=5, reruns_delay=2)
def test_example():
    import random
    assert random.choice([True, False])

@pytest.mark.flaky(reruns=5, reruns_delay=2, reruns_delay_backoff_factor=2)
def test_example():
    import random
    assert random.choice([True, False])

You can also specify an optional condition in the re-run marker:

@pytest.mark.flaky(reruns=5, condition=sys.platform.startswith("win32"))
def test_example():
   import random
   assert random.choice([True, False])

Exception filtering can be accomplished by specifying regular expressions for only_rerun and rerun_except. They override the --only-rerun and --rerun-except command line arguments, respectively.

Arguments can be a single string:

@pytest.mark.flaky(rerun_except="AssertionError")
def test_example():
    raise AssertionError()

Or a list of strings:

@pytest.mark.flaky(only_rerun=["AssertionError", "ValueError"])
def test_example():
    raise AssertionError()

Exception classes are also accepted and match any subclass:

@pytest.mark.flaky(only_rerun=[AssertionError, ValueError])
def test_example():
    raise AssertionError()

You can use @pytest.mark.flaky(condition) similarly as @pytest.mark.skipif(condition), see pytest-mark-skipif

@pytest.mark.flaky(reruns=2,condition="sys.platform.startswith('win32')")
def test_example():
    import random
    assert random.choice([True, False])
# totally same as the above
@pytest.mark.flaky(reruns=2,condition=sys.platform.startswith("win32"))
def test_example():
  import random
  assert random.choice([True, False])

Note that the test will re-run for any condition that is truthy.

Force rerun count

To force a specific re-run count globally, irrespective of the number of re-runs specified in test markers, pass --force-reruns:

$ pytest --force-reruns 5

Rerun mode

By default the marker count takes strict priority over the global --reruns setting. To make them additive instead, pass --reruns-mode=append. With append, a test decorated with @pytest.mark.flaky(reruns=2) run with --reruns 4 will be re-run up to 2 + 4 = 6 times:

$ pytest --reruns 4 --reruns-mode append

Limit total reruns across the suite

To cap the total number of reruns across the entire test suite regardless of how many individual tests fail, pass --max-suite-reruns. Once the limit is reached, no further reruns occur even if individual tests have remaining reruns:

$ pytest --reruns 3 --max-suite-reruns 10

This is useful in large test suites to bound resource usage when many tests are flaky at the same time. The cap applies after rerun selection, including tests configured with --force-reruns and @pytest.mark.flaky.

Show tracebacks for retried failures

By default only the final attempt of a flaky test produces a traceback, so failures from earlier attempts (including those of tests that ultimately pass after a rerun) are silently discarded. To inspect them, pass --rerun-show-tracebacks:

$ pytest --reruns 2 --rerun-show-tracebacks

Each retried attempt’s traceback is appended to the rerun test summary info section. The section is emitted automatically when the flag is set, so -rR is not required.

Output

Here’s an example of the output provided by the plugin when run with --reruns 2 and -r aR:

test_report.py RRF

================================== FAILURES ==================================
__________________________________ test_fail _________________________________

    def test_fail():
>       assert False
E       assert False

test_report.py:9: AssertionError
============================ rerun test summary info =========================
RERUN test_report.py::test_fail
RERUN test_report.py::test_fail
FAILED test_report.py::test_fail
============================ short test summary info =========================
FAIL test_report.py::test_fail
======================= 1 failed, 2 rerun in 0.02 seconds ====================

Note that output will show all re-runs. Tests that fail on all the re-runs will be marked as failed.

Compatibility

• This plugin is not compatible with pytest-xdist’s –looponfail flag.

• This plugin is not compatible with the core –pdb flag.

• This plugin is not compatible with the plugin flaky, you can only have pytest-rerunfailures or flaky but not both.

Priority

You can specify arguments in three places. So if you set the number of reruns in all three, which one takes priority?

• Top priority is the marker, such as @pytest.mark.flaky(reruns=1)

• Second priority is what’s specified on the command line, like --reruns=2

• Last priority is the pyproject.toml (or pytest.ini) file setting, like reruns = 3

The same order applies to the rerun filters: a marker’s only_rerun / rerun_except beats --only-rerun / --rerun-except on the command line, which in turn beats the only_rerun / rerun_except ini settings.

Additionally, all three can be overridden by passing --force-reruns argument on the command line. Passing --reruns-mode=append makes the marker count and the global --reruns / reruns ini setting additive instead of strict.

Resources

• Issue Tracker

• Code

Development

• Test execution count can be retrieved from the execution_count attribute in test item’s object. Example:

  @hookimpl(tryfirst=True)
  def pytest_runtest_makereport(item, call):
      print(item.execution_count)

16.7 (2026-09-17)

16.6.1 (2026-09-03)

16.6 (2026-08-17)

16.5 (2026-08-13)

16.4 (2026-07-01)

16.3 (2026-05-22)

16.2 (2026-05-13)

16.1 (2025-10-10)

• Drop support for Python 3.9.

• Changed “localhost” to “127.0.0.1” to avoid bad hostname resolution.

• Added --force-reruns to override rerun count globally. Fixes #306.

16.0.1 (2025-09-02)

• Reverted the ability to access error attributes because of an incompatibility with pytest-xdist. Fixes #302, #303.

16.0 (2025-08-29)

15.1 (2025-05-08)

15.0 (2024-11-20)

14.0 (2024-03-13)

13.0 (2023-11-22)

12.0 (2023-07-05)

11.1.2 (2023-03-09)

11.1.1 (2023-02-17)

11.1 (2023-02-09)

11.0 (2023-01-12)

10.2 (2021-09-17)

10.1 (2021-07-02)

10.0 (2021-05-26)

9.1.1 (2020-09-29)

9.1 (2020-08-26)

9.0 (2020-03-18)

8.0 (2019-11-18)

7.0 (2019-03-28)

6.0 (2019-01-08)

5.0 (2018-11-06)

• Drop support for pytest versions < 3.6 to reduce the maintenance burden.

• Add support up to pytest version 3.10. Thus supporting the newest 5 pytest releases.

• Add support for Python 3.7.

• Fix issue can occur when used together with pytest-flake8 (#73)

4.2 (2018-10-04)

• Fixed #64 issue related to setup_class and fixture executions on rerun (Thanks to @OlegKuzovkov for the PR).

• Added new execution_count attribute to reflect the number of test case executions according to #67 issue. (Thanks to @OlegKuzovkov for the PR).

4.1 (2018-05-23)

• Add support for pytest 3.6 by using Node.get_closest_marker() (Thanks to @The-Compiler for the PR).

4.0 (2017-12-23)

• Added option to add a delay time between test re-runs (Thanks to @Kanguros for the PR).

• Added support for pytest >= 3.3.

• Drop support for pytest < 2.8.7.

3.1 (2017-08-29)

• Restored compatibility with pytest-xdist. (Thanks to @davehunt for the PR)

3.0 (2017-08-17)

• Add support for Python 3.6.

• Add support for pytest 2.9 up to 3.2

• Drop support for Python 2.6 and 3.3.

• Drop support for pytest < 2.7.

2.2 (2017-06-23)

• Ensure that other plugins can run after this one, in case of a global setting --rerun=0. (Thanks to @sublee for the PR)

2.1.0 (2016-11-01)

• Add default value of reruns=1 if pytest.mark.flaky() is called without arguments.

• Also offer a distribution as universal wheel. (Thanks to @tltx for the PR)

2.0.1 (2016-08-10)

• Prepare CLI options to pytest 3.0, to avoid a deprecation warning.

• Fix error due to missing CHANGES.rst when creating the source distribution by adding a MANIFEST.in.

2.0.0 (2016-04-06)

• Drop support for Python 3.2, since supporting it became too much of a hassle. (Reason: Virtualenv 14+ / PIP 8+ do not support Python 3.2 anymore.)

1.0.2 (2016-03-29)

• Add support for --resultlog option by parsing reruns accordingly. (#28)

1.0.1 (2016-02-02)

• Improve package description and include CHANGELOG into description.

1.0.0 (2016-02-02)

• Rewrite to use newer API of pytest >= 2.3.0

• Improve support for pytest-xdist by only logging the final result. (Logging intermediate results will finish the test rather rerunning it.)