---
id: pytest-stub
version: "1.1.0"
license: BSD 3-Clause License
license_treatment: permissive
maintenance: abandoned
---

# pytest-stub — Stub packages, modules and attributes.

License: permissive · Maintenance: abandoned · Downloads: 94.8K/mo

## What it is and what it does

pytest-stub is a pytest plugin that intercepts imports and replaces external dependencies with stubs—either auto-generated placeholders (functions, classes, mocks) or custom objects you provide. This lets you test code that depends on heavy or unavailable libraries (like OpenCV, Django, or NumPy) without installing them, which is useful when testing a library that uses those dependencies but you want to isolate your test environment.

The plugin works via a `stub` fixture in individual tests or a global `stub_global()` function in conftest.py. You pass a dictionary mapping import paths to stub types: `'[func]'` generates a function, `'[cls]'` generates a class, `'[mock]'` generates a MagicMock, and `'[mock_persist]'` generates a persistent mock. You can also provide custom objects directly. The stubs are applied before test execution so imports succeed without the actual dependency present.

Use it for:

- Test a library that depends on OpenCV or NumPy without installing those heavy packages in your CI environment.
- Isolate tests of Django-related code by stubbing django.core.management and django.conf modules.
- Verify that your code handles missing or unavailable dependencies gracefully without actually removing them.
- Speed up test runs by replacing slow-to-import or slow-to-initialize external libraries with lightweight stubs.
- Test code paths that use optional dependencies without requiring those dependencies to be installed.

## Worth the install?

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

A pytest plugin that replaces package, module, and attribute dependencies with stubs—either auto-generated (functions, classes, mocks) or custom objects—so you can test code that depends on external libraries without installing them.

Yes, if you need to test code with external dependencies you don't want to install—the plugin is simple and has no runtime dependencies. However, maintenance is abandoned (last release 2020-04-28), so compatibility with Python versions beyond 3.8 is unverified and you should test it in your environment first. For active projects, consider whether a maintained alternative or manual mocking would be more reliable long-term.

## Install

pip install pytest-stub
uv add pytest-stub
poetry add pytest-stub

## Installing pytest-stub

Before you install: Low install friction with no runtime dependencies. Maintenance is inactive—last release was 2020-04-28 and the repository shows no recent activity—so you should expect no bug fixes or updates for new Python versions beyond those already listed.

License in practice: BSD 3-Clause License is permissive and imposes minimal restrictions; you can use this package freely in commercial and private projects with only attribution required.

Quickstart:

# Install
pip install pytest-stub

# In your test file
def test_example(stub):
    stub.apply({
        'django.core.management.call_command': '[func]',
        'cv2': '[mock]',
    })

Requires pytest >= 2.9.0 and Python 3.6 or later.

Verify before relying:

- Whether the package works reliably with Python versions newer than 3.8 (last tested version in classifiers).
- Whether auto-generated stubs ([func], [cls], [mock], [mock_persist]) behave correctly for complex dependency signatures.
- Current compatibility with modern pytest versions and whether any breaking changes have occurred since 2020.

## Package facts

- License: BSD 3-Clause License (permissive)
- Python support: unspecified
- Install friction: low
- Maintenance: abandoned
- Downloads: 94.8K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

pytest dependency stubbing, mock external packages in tests, stub modules pytest, test without dependencies, pytest fixture stubs, replace imports in tests, pytest mock packages, pytest-plugin, test-isolation, dependency-mocking

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