Install & Compatibility
Where this runs
tested against v3.15.1 · 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.2MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.3s · import 0.000s · 32MB
30MB installed
● package 30MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
mocker
✓ def test_example(mocker): ...
The `mocker` fixture is automatically provided by pytest-mock; no explicit import statement is usually needed for the fixture itself.
MockType
✓ from pytest_mock import MockType
Available for type annotation purposes since v3.14.0.
AsyncMockType
✓ from pytest_mock import AsyncMockType
Available for type annotation purposes since v3.14.0.
This quickstart demonstrates using the `mocker` fixture to patch `os.path.exists` and `builtins.open` to simulate file system interactions without touching actual files. The first test verifies behavior when a file exists, and the second when it doesn't. `mocker.patch` automatically handles cleanup after each test.
import os
class MyService:
def read_config(self, filename):
if not os.path.exists(filename):
return {}
with open(filename, 'r') as f:
return {'data': f.read()}
def test_read_config_file_exists(mocker):
mock_exists = mocker.patch('os.path.exists', return_value=True)
mock_open = mocker.patch('builtins.open', mocker.mock_open(read_data='key: value'))
service = MyService()
result = service.read_config('config.txt')
mock_exists.assert_called_once_with('config.txt')
mock_open.assert_called_once_with('config.txt', 'r')
assert result == {'data': 'key: value'}
def test_read_config_file_not_exists(mocker):
mocker.patch('os.path.exists', return_value=False)
mocker.patch('builtins.open', side_effect=FileNotFoundError)
service = MyService()
result = service.read_config('non_existent.txt')
assert result == {}
Debug
Known issues
breakingSupport for older Python versions is frequently dropped. Python 3.8 support was dropped in v3.15.0, Python 3.7 in v3.12.0, and Python 3.5 in v3.6.0.fixEnsure your project runs on a supported Python version (currently >=3.9 for v3.15.1).
affects: >=3.15.0 (Python 3.8), >=3.12.0 (Python 3.7), >=3.6.0 (Python 3.5)
breakingWhen using `mocker.spy` on functions that return iterators (e.g., `itertools._tee` objects), you now must explicitly pass `duplicate_iterators=True` to avoid `AttributeError` when accessing `spy_return` or `spy_return_iter`.fixFor `mocker.spy` calls on iterators, update to `mocker.spy(obj, 'method', duplicate_iterators=True)`.
affects: >=3.15.1
breakingpytest-mock now requires `pytest>=6.2.5`. Older pytest versions will cause installation or runtime issues.fixUpgrade your pytest installation: `pip install --upgrade pytest`.
affects: >=3.13.0
breakingThe `setup.py` file was removed. Projects relying on `setup.py install` or similar direct invocations will need to update their build process to use standard `pip install` or `pyproject.toml` based builds.fixRefer to the Python packaging documentation or project's `pyproject.toml` for modern installation methods. Avoid direct `python setup.py install`.
affects: >=3.13.0
gotchaPrior to v3.14.0, `mocker.patch.object` could sometimes fail to be properly cleared between tests, leading to unexpected test interactions or failures.fixUpgrade to `pytest-mock>=3.14.0` to ensure `mocker.patch.object` is correctly cleared. Manually call `mocker.stopall()` or ensure mocks are short-lived if upgrading is not an option.
affects: <3.14.0
gotchaWhile `unittest.mock` supports decorators and context managers for patching, `pytest-mock` prefers the `mocker` fixture. Using `mock.patch` as a decorator or context manager directly with `pytest-mock` may cause warnings or unexpected behavior, as the fixture handles cleanup automatically.fixAlways prefer `mocker.patch()`, `mocker.patch.object()`, etc., within your test functions rather than `unittest.mock` decorators or `with patch(...)` statements when using `pytest-mock`.
affects: All versions
gotchaThe system package manager `pip` issued warnings or notices during installation or environment setup, unrelated to pytest-mock's functionality. These typically advise on best practices like using virtual environments, avoiding running as root, or updating pip itself.fixReview the pip output for specific recommendations, such as running pip in a virtual environment (`python -m venv .venv; source .venv/bin/activate; pip install ...`), avoiding running as the root user, and ensuring pip is up-to-date (`pip install --upgrade pip`). These are typically environment-specific best practices rather than pytest-mock issues.
affects: All versions
Errors
Common errors & fixes
NameError: name 'mocker' is not defined
The 'mocker' fixture is not recognized, usually because `pytest-mock` is not installed, or the test function is not accepting 'mocker' as an argument.
fixEnsure `pytest-mock` is installed (`pip install pytest-mock`) and that your test function includes `mocker` in its signature (e.g., `def test_something(mocker):`).
ModuleNotFoundError: No module named 'pytest_mock'
The `pytest-mock` library has not been installed in the Python environment where pytest is being run.
fixInstall the library using pip: `pip install pytest-mock`.
AttributeError: module 'your_module' has no attribute 'some_function'
You are attempting to patch a function, class, or attribute at a location where it does not exist *at the time the code under test looks it up*. This often happens when patching the original definition instead of where it's imported and used within the module being tested.
fixIdentify the exact location (module path) where the object is *looked up* by the code you are testing and patch it there. For example, if `my_module.py` imports `external_func` from `external_lib` and calls it, you should patch `my_module.external_func` instead of `external_lib.external_func`.
TypeError: 'MagicMock' object is not callable
This error occurs when you attempt to call a mock object that was not configured to be callable, or when you incorrectly call a mocked attribute that is not a function or method in the real object (especially with `autospec`), or when a mock's `return_value` is set to a non-callable object which is then erroneously called by the tested code.
fixEnsure that the mock is configured to be callable if needed (e.g., by default, `mocker.patch` creates a callable mock). If mocking a property, use `new_callable=mocker.PropertyMock`. If the `return_value` of a mock is expected to be called, ensure it's set to a callable object or another mock.
Upgrade
Version history
3.15.1latest on PyPI · released Sep 16, 2025
Audit
Dependencies
pytestrequiredRequired as a pytest plugin; version >=6.2.5 is needed since pytest-mock v3.13.0.
pythonrequiredRequires Python >=3.9 since pytest-mock v3.15.0.