Install & Compatibility
Where this runs
tested against v1.6.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 31.3MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.7s · import 0.000s · 32MB
30MB installed
● package 30MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
fake_process
✓ def test_something(fake_process):
# use fake_process here
The `fake_process` fixture (or its alias `fp`) is automatically provided by the plugin to your test functions. No explicit import statement for the fixture itself is needed in your test file.
This example demonstrates how to use the `fp` (alias for `fake_process`) fixture to register a command and define its `stdout`. When `subprocess.run()` is called with the registered command, `pytest-subprocess` intercepts it and provides the faked output and return code.
import subprocess
import pytest
def test_process_command(fp):
# Register a fake command and its expected output
fp.register(['fake-command'], stdout='Hello from fake-command')
# Run the command using subprocess (it will be faked by pytest-subprocess)
process = subprocess.run(['fake-command'], capture_output=True, text=True)
# Assert on the faked process's behavior
assert process.returncode == 0
assert process.stdout.strip() == 'Hello from fake-command'
def test_command_with_args(fp):
fp.register(['greet', 'world'], stdout='Greeting world!')
process = subprocess.run(['greet', 'world'], capture_output=True, text=True)
assert process.returncode == 0
assert process.stdout.strip() == 'Greeting world!'
Debug
Known issues
gotchaOn Python 3.12+, versions prior to 1.5.4 might lead to `ResourceWarning` for unclosed file handles when using `universal_newlines` or `text` arguments with `subprocess.Popen`.fixUpgrade to `pytest-subprocess` 1.5.4 or newer. Alternatively, ensure explicit closing of `process.stdout`.
affects: <1.5.4
gotchaOlder versions (prior to 1.5.3) contained an incorrect wait timeout calculation, which could lead to unreliable timeout behavior in tests.fixUpgrade to `pytest-subprocess` 1.5.3 or newer to ensure correct timeout calculations.
affects: <1.5.3
gotchaWhen running on Windows with Python versions prior to 3.8, passing `Path` objects as arguments to `subprocess` functions might result in a `TypeError`.fixUpgrade Python to 3.8+ on Windows, or convert `Path` objects to strings before passing them to `subprocess` commands.
affects: >=1.5.0, Python < 3.8 on Windows
breakingPrior to version 1.4.2, exceptions raised within callback functions passed to `register()` might have been silently ignored by `communicate()`. Version 1.4.2 changed this behavior to raise these exceptions, which could break tests relying on the silent failure.fixUpdate tests to handle or expect exceptions from callbacks if you are upgrading from a version older than 1.4.2. Review callback implementations to ensure they behave as expected with the new error propagation.
affects: <1.4.2
gotchaBy default, any attempt to run a `subprocess` command that has NOT been registered using `fp.register()` will raise a `ProcessNotRegisteredError`.fixExplicitly register all commands you intend to fake. If you need to allow some commands to execute as real processes, use `fp.allow_unregistered(True)` or `fp.pass_command(['some-real-command'])`.
affects: All versions
gotchaWhen using `pytest-cov` to measure coverage of code run in subprocesses, `pytest-cov`'s environment variables must be explicitly passed to the subprocess. If these are not passed, coverage for the subprocess might not be collected.fixEnsure that `os.environ` or relevant `COV_*` environment variables are passed to the `env` argument of `subprocess.Popen` or `subprocess.run` calls within your tests. For example: `subprocess.run(command, env={**os.environ, **your_custom_env})`. affects: All versions when combined with `pytest-cov`
Upgrade
Version history
1.6.0latest on PyPI · released May 10, 2026
Audit
Dependencies
pytestrequiredThis is a pytest plugin and requires pytest to function.