---
id: pytest-run-parallel
version: "0.10.0"
license: MIT
license_treatment: permissive
maintenance: active
---

# pytest-run-parallel — A simple pytest plugin to run tests concurrently

License: permissive · Maintenance: active · Downloads: 230.5K/mo

## What it is and what it does

pytest-run-parallel is a pytest plugin that executes test functions multiple times concurrently in a thread pool, rather than running different tests in parallel. Its primary purpose is stress-testing code for thread-safety issues, especially important for libraries that use C extensions and will run under free-threaded Python (PEP 703). The plugin is not a replacement for pytest-xdist; it focuses on discovering race conditions and GIL-related bugs by running the same test repeatedly across multiple threads with synchronized startup via a barrier.

The plugin provides command-line flags (--parallel-threads, --iterations, --skip-thread-unsafe, --forever) and per-test markers to control thread count and iteration behavior. It includes fixtures for thread and iteration indices, and patches tmp_path and tmpdir to be thread-safe. A key caveat: pytest itself is not thread-safe, so tests must account for shared fixture state across threads and avoid dynamically setting marks.

Use it for:

- Validate that C extension libraries work correctly under free-threaded Python builds before PEP 703 adoption
- Stress-test thread safety of libraries by running the same test repeatedly in parallel threads to catch race conditions
- Detect GIL-related bugs and verify behavior when the GIL is disabled in CPython implementations
- Reproduce intermittent threading bugs by running tests in an endless loop (--forever) until failure occurs
- Verify that pytest fixtures and test setup code handle concurrent access without data corruption

## Worth the install?

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

A pytest plugin that runs test functions concurrently in a thread pool to discover thread-safety issues, particularly useful for validating C library compatibility with free-threaded Python implementations.

Yes, if you maintain a library with C extensions or are preparing for free-threaded Python adoption. The plugin is actively maintained, has no security vulnerabilities, and solves a specific and growing need. Install with caution if your test suite relies heavily on mutable shared state via fixtures—you will need to refactor tests to be thread-safe first.

## Install

pip install pytest-run-parallel
uv add pytest-run-parallel
poetry add pytest-run-parallel

## Installing pytest-run-parallel

Before you install: Low friction: pure Python wheel with only pytest as a runtime dependency. Actively maintained with a recent release (10 days old) and steady development since first release in 2024-09-30.

License in practice: MIT license permits unrestricted use, modification, and distribution with minimal obligations—suitable for any project type.

Quickstart:

pip install pytest-run-parallel

# In your test file:
import pytest

def test_example():
    assert True

# Run with: pytest --parallel-threads=4 test_example.py

Requires Python 3.10 or later. Pytest itself is not thread-safe; tests must be designed to handle shared state across threads, and fixtures like tmp_path are patched but stateful fixtures remain shared.

Verify before relying:

- Whether psutil optional dependency is automatically detected or must be explicitly installed for CPU core detection
- Actual performance gains or overhead compared to serial execution for typical test suites
- Compatibility with other pytest plugins beyond xdist

## Package facts

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

## Tags

pytest concurrent test execution, thread safety testing, multithreaded pytest plugin, free-threaded python testing, pytest stress testing threads, c library thread safety, pytest parallel threads, thread-safety, free-threading, stress-testing

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