pytest-run-parallel

0.8.2 verified Mon Apr 27 auth: no python

A pytest plugin to run tests concurrently using threads. It automatically detects thread-unsafe tests (e.g., using fixtures like tmp_path, monkeypatch, capsys, or mocking) and marks them as serial. Version 0.8.2 supports Python >=3.9. Releases are intermittent.

pip install pytest-run-parallel

Common errors

error AttributeError: module 'pytest_run_parallel' has no attribute '...' ↓

cause Trying to import the plugin directly instead of relying on pytest's plugin discovery.

fix

Remove any explicit imports of pytest_run_parallel. The plugin is auto-discovered when installed.

error TypeError: unsupported operand type(s) for +: 'int' and 'NoneType' ↓

cause Using --parallel-threads with a value that cannot be parsed as integer (e.g., --parallel-threads=auto without proper string handling in older versions).

fix

Use --parallel-threads=N where N is an integer, or use 'auto' (supported since v0.5.0).

error pytest: error: unrecognized arguments: --parallel-threads ↓

cause The plugin is not installed or not enabled.

fix

Ensure pytest-run-parallel is installed in the current environment (pip install pytest-run-parallel).

error RuntimeError: cannot start new thread ↓

cause The --parallel-threads value is too high for the system (e.g., >1000).

fix

Reduce the number of parallel threads. Use a sane value like 4 or 'auto'.

Warnings

gotcha The plugin automatically detects thread-unsafe patterns (fixtures like tmp_path, monkeypatch, capsys, etc.). If your test uses these, it will run serially, even with --parallel-threads. No explicit mark needed. ↓

fix To force parallelism on a test that uses thread-unsafe fixtures, mark it with @pytest.mark.parallel. However, this may cause flaky tests.

breaking In v0.8.0, the --parallel-threads-limit mark was added. Before that, you could only set global parallelism. Also, gc.collect detection was added in v0.8.0, marking tests using gc.collect as thread-unsafe. ↓

fix If you rely on gc.collect in tests, they will now run serially unless you use --disable-thread-unsafe-detection or mark them as parallel.

deprecated The --forever flag interaction with pytest-xdist changed in v0.7.1. The flag may not work as expected when used with xdist. ↓

fix Avoid using --forever with pytest-xdist. Use --parallel-threads instead for parallel execution.

gotcha Tests that use unittest.mock or fixtures like monkeypatch are automatically detected as thread-unsafe and run serially. This includes MagicMock, patch, etc. ↓

fix If you know your mock usage is safe, you can disable detection with --disable-thread-unsafe-detection, but be careful about race conditions.

Imports

pytest_run_parallel
wrong
```
import pytest_run_parallel
```
correct
```
pytest_plugins = ['pytest_run_parallel']
```
This is a pytest plugin; it's auto-discovered when installed. No explicit import needed in conftest.

Quickstart

Run pytest with parallel threads. The plugin automatically parallelizes tests unless they are detected as thread-unsafe.

# In your project root, run:
pytest --parallel-threads=auto
# Or set a fixed number:
pytest --parallel-threads=4
# To detect thread-unsafe tests (default on):
pytest --parallel-threads=auto --detect-thread-unsafe