---
id: pytest-examples
version: "0.0.18"
license: MIT
license_treatment: permissive
maintenance: active
---

# pytest-examples — Pytest plugin for testing examples in docstrings and markdown files.

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

## What it is and what it does

pytest-examples is a pytest plugin that discovers and validates Python code examples embedded in docstrings and markdown files. It integrates black and ruff to lint examples for style compliance, runs them to verify they execute without error, and can verify that print statements in the code match their expected output (marked with `#>` comments). The plugin can also update examples in place to auto-format code and insert or refresh print statement annotations.

Typical use involves writing a pytest test that parametrizes over examples found in a directory or file, then calling methods like `lint()`, `run()`, `run_print_check()`, or `run_print_update()` on each example. This ensures documentation code stays correct and executable as the underlying library evolves.

Use it for:

- Verify that code examples in API documentation actually run without errors
- Enforce consistent code style in docstrings and README examples using ruff and black
- Validate that printed output in documented examples matches what the code actually produces
- Automatically update and reformat all code examples across a project in one pass
- Catch broken examples early in CI when documentation is changed alongside code

## Worth the install?

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

A pytest plugin that finds, lints, runs, and validates Python code examples embedded in docstrings and markdown files, using ruff and black for formatting and checking print statement correctness.

Yes. The plugin fills a real gap—keeping documentation examples in sync with code—and is actively maintained with no known vulnerabilities. Low install friction and permissive MIT license make it a straightforward addition to any pytest-based test suite. Install if you maintain libraries with documented examples and want them to stay correct.

## Install

pip install pytest-examples
uv add pytest-examples
poetry add pytest-examples

## Installing pytest-examples

Before you install: Low friction install with three runtime dependencies (black, pytest, ruff). Active maintenance with recent commits; last release 465 days ago but repository remains actively developed.

License in practice: MIT license permits free use, modification, and distribution with minimal restrictions—suitable for most commercial and open-source projects.

Quickstart:

pip install pytest-examples

import pytest
from pytest_examples import find_examples, CodeExample, EvalExample

@pytest.mark.parametrize('example', find_examples('docs'), ids=str)
def test_examples(example: CodeExample, eval_example: EvalExample):
    eval_example.lint(example)
    eval_example.run(example)

Verify before relying:

- Whether the plugin works with pytest versions beyond those implicitly tested in CI
- Performance characteristics when scanning large codebases with many examples

## Package facts

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

## Tags

pytest plugin docstring examples, test code examples in docstrings, validate markdown code blocks, lint and run embedded python examples, check print statements in examples, docstring code testing, documentation-testing, code-validation

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