---
id: pytest-forked
version: "1.7.5"
license: MIT
license_treatment: permissive
maintenance: active
---

# pytest-forked — run tests in isolated forked subprocesses

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

## What it is and what it does

pytest-forked is a pytest plugin that isolates each test by running it in a forked subprocess. This allows tests involving C or C++ libraries—or any code prone to crashing—to fail gracefully without terminating the entire test run. A segfault or process death in one test does not affect subsequent tests.

The plugin is extracted from pytest-xdist's --forked module and can be used standalone with the --forked CLI flag, applied per-test via the @pytest.mark.forked decorator, or combined with pytest-xdist's parallel execution (e.g., pytest -n3 --forked) to run multiple test subprocesses in parallel, each forking individual tests. It is not available on Windows due to the absence of fork() support.

Use it for:

- Testing C/C++ bindings or extension modules that may crash the Python interpreter.
- Running tests with monkey-patched global state that could leak between tests.
- Detecting and reporting segfaults as test failures rather than suite termination.
- Combining with pytest-xdist to parallelize tests while isolating crash-prone code.
- Validating cleanup and teardown in tests that modify process-level state.

## Worth the install?

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

A pytest plugin that runs each test in a forked subprocess to isolate crashes and segfaults, preventing a single test failure from terminating the entire test suite.

Yes, if you test C/C++ libraries or crash-prone code on POSIX systems. The low install friction and active maintenance make it a straightforward addition to test suites that need crash isolation. Not applicable on Windows. The inactive status means minimal new features, but the core functionality is stable and the plugin remains functional.

## Install

pip install pytest-forked
uv add pytest-forked
poetry add pytest-forked

## Installing pytest-forked

Before you install: Low friction install with a single runtime dependency on pytest. Actively maintained as of the latest release; however, the package is classified as Development Status 7 - Inactive, indicating minimal ongoing feature work.

License in practice: MIT license permits commercial and private use with minimal restrictions; suitable for most projects.

Quickstart:

pip install pytest-forked

pytest --forked

# Or mark individual tests:
@pytest.mark.forked
def test_with_leaky_state():
    pass

Does not work on Windows; requires a POSIX system with fork() support (Linux, macOS). Requires Python 3.10 or later.

Verify before relying:

- Whether the plugin works correctly with pytest-xdist in all configurations beyond the documented -n3 --forked example.
- Performance overhead of forking per test compared to in-process execution.

## Package facts

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

## Tags

pytest subprocess isolation, test process crash recovery, forked test execution, segfault handling pytest, isolated test processes, pytest crash isolation, subprocess test boxing, subprocess-isolation, crash-recovery, c-extension-testing

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