---
id: pytest-random-order
version: "1.2.0"
license: MIT
license_treatment: permissive
maintenance: active
---

# pytest-random-order — Randomise the order in which pytest tests are run with some control over the randomness

License: permissive · Maintenance: active · Downloads: 2.8M/mo

## What it is and what it does

pytest-random-order is a pytest plugin that shuffles the order in which tests execute, with fine-grained control over randomization scope. By default it does not randomize; you opt in via command-line flag or configuration. The plugin groups tests into buckets (by class, module, package, or globally) and shuffles within and across buckets, allowing you to detect tests that pass only because they run after another test that leaves the system in a particular state—a common source of hidden test fragility.

The plugin reports the random seed used in each run, so if a specific test order reveals a failure, you can reproduce it exactly by passing that seed back. It also supports disabling randomization for specific modules or classes, respects pytest's failed-first flag, and can be disabled entirely if needed. It integrates seamlessly as a pytest plugin with no external dependencies beyond pytest itself.

Use it for:

- Detect tests that depend on execution order or shared state by running them in random order and catching failures that don't occur in default order.
- Reproduce a specific test failure by rerunning with the seed value reported in the original test output.
- Verify test isolation at module or package scope before moving to more aggressive global randomization.
- Disable randomization for known-fragile test classes while randomizing the rest of the suite.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

A pytest plugin that randomizes the order in which tests run, helping detect test interdependencies and order-dependent failures.

Yes. This is a lightweight, actively maintained plugin with zero security issues and a clear, narrow purpose: catching test order dependencies. Install it if you want to harden your test suite against hidden interdependencies. The opt-in design means it won't affect existing test runs unless you explicitly enable it.

## Install

pip install pytest-random-order
uv add pytest-random-order
poetry add pytest-random-order

## Installing pytest-random-order

Before you install: Low friction: pure Python wheel with only pytest as a runtime dependency. Actively maintained with recent commits and stable production status.

License in practice: MIT license is permissive; you can use, modify, and distribute this package freely with minimal restrictions.

Quickstart:

pip install pytest-random-order

# In pytest.ini or pyproject.toml:
# [pytest]
# addopts = --random-order

# Or run: pytest --random-order

Requires Python 3.9 or later.

Verify before relying:

- Whether the plugin's bucket types (class, module, package, global, etc.) cover all real-world test organization patterns users encounter.

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 2.8M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

pytest test order randomization, detect test dependencies, pytest shuffle tests, test isolation verification, pytest random seed reproducible, test-quality, pytest-plugin

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