---
id: pytest-subprocess
version: "1.6.0"
license: MIT
license_treatment: permissive
maintenance: active
---

# pytest-subprocess — A plugin to fake subprocess for pytest

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

## What it is and what it does

pytest-subprocess is a pytest plugin that intercepts calls to subprocess.Popen and its higher-level wrappers (subprocess.run, subprocess.call, subprocess.check_call, subprocess.check_output) to replace them with fake implementations. Instead of executing real system commands during tests, you register expected commands and their outputs using the fp fixture, which then returns those outputs when your code calls subprocess. This eliminates test dependencies on external tools, makes tests faster and more reliable, and lets you simulate error conditions and edge cases that would be hard to trigger with real processes.

The plugin supports registering different outputs for repeated calls to the same command, passing input to stdin with custom handling logic, allowing unregistered commands to fall through to real subprocess execution, and using callbacks to inject custom behavior. It works across all subprocess functions because they all ultimately call Popen internally. The fixture is available both as fp and the longer form fake_process.

Use it for:

- Test code that shells out to git, docker, or other CLI tools without requiring those tools to be installed or available in CI
- Simulate subprocess failures and non-zero exit codes to verify error handling paths in your application
- Mock multi-step command sequences where each call returns different output, testing state-dependent subprocess behavior
- Verify that your code passes the correct arguments and environment to subprocess without actually executing them
- Test subprocess input/output handling by registering stdin callbacks that transform input into output

## Worth the install?

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

Pytest plugin that intercepts and fakes subprocess calls, allowing you to register mock process outputs and behaviors without executing real commands.

Yes. This is a mature, actively maintained plugin with no security issues, low install friction, and a permissive license. It directly solves the common testing problem of isolating code that calls external processes. Install it if your test suite includes code that uses subprocess.

## Install

pip install pytest-subprocess
uv add pytest-subprocess
poetry add pytest-subprocess

## Installing pytest-subprocess

Before you install: Low friction install with a single runtime dependency (pytest). The package is actively maintained with a recent release and no known vulnerabilities, making it straightforward to add to test suites.

License in practice: MIT license is permissive, allowing use in commercial and open-source projects with minimal restrictions—just include the license text.

Quickstart:

pip install pytest-subprocess

import subprocess

def test_example(fp):
    fp.register(["echo", "hello"], stdout="hello")
    result = subprocess.run(["echo", "hello"], capture_output=True, text=True)
    assert result.stdout == "hello"

Verify before relying:

- Whether the plugin works with subprocess.Popen subclasses or only the standard library implementation
- Performance overhead when registering many subprocess calls in a single test suite

## Package facts

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

## Tags

mock subprocess calls in tests, fake subprocess for pytest, test code that runs external commands, pytest subprocess mocking, intercept subprocess.Popen, register fake process output, unit test subprocess without real execution, subprocess-mocking, test-isolation

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