pytest-run-parallel

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 on this page — 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

pytest-run-parallel on PyPI

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

Evidence: pytest_run_parallel-0.10.0-py3-none-any.whl

Tags

More Testing packages