---
id: pytest-codeblocks
version: "0.18.0"
license: The MIT License (MIT) Copyright (c) 2020-present Nico Schlömer Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the… (full text in the JSON record)
license_treatment: permissive
maintenance: active
---

# pytest-codeblocks — Test code blocks in your READMEs

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

## What it is and what it does

pytest-codeblocks is a pytest plugin that treats code blocks in markdown files—particularly READMEs—as executable test cases. It discovers blocks marked with python, sh, bash, or zsh syntax highlighting and runs them through pytest, letting you verify that documentation examples actually work.

The plugin supports marking code blocks with pytest directives (skip, skipif, xfail) via HTML comments, merging fragmented examples across multiple blocks, and validating expected output. This catches a common documentation debt: examples that drift out of sync with the actual codebase. It depends only on pytest and requires Python 3.10 or later.

Use it for:

- Verify that code examples in a project's README actually execute without errors.
- Catch breaking changes when refactoring by running documented usage patterns as tests.
- Validate shell command sequences and their output in installation or setup documentation.
- Ensure multi-step code examples work when split across separate markdown blocks.
- Skip or mark code blocks as expected-to-fail for examples that demonstrate error handling.

## Worth the install?

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

A pytest plugin that automatically discovers and runs Python and shell code blocks from README and markdown files as test cases.

Yes. Low install friction, no security vulnerabilities, permissive MIT license, and active maintenance make this a straightforward addition to any project with documentation that includes runnable code. It solves a real problem—keeping examples in sync with code—with minimal overhead.

## Install

pip install pytest-codeblocks
uv add pytest-codeblocks
poetry add pytest-codeblocks

## Installing pytest-codeblocks

Before you install: Low friction install with a single runtime dependency on pytest. Actively maintained with a release within the last 60 days and marked as Production/Stable.

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

Quickstart:

pip install pytest-codeblocks

# In your README.md, add code blocks with python or sh syntax highlighting
# Then run:
pytest --codeblocks

Requires Python 3.10 or later.

Verify before relying:

- Whether the plugin handles edge cases like nested code blocks or complex markdown structures.
- Performance characteristics when testing large numbers of code blocks across many files.

## Package facts

- License: The MIT License (MIT) Copyright (c) 2020-present Nico Schlömer Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the… (full text in the JSON record) (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 186.4K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

test code blocks in markdown, readme code example testing, pytest markdown plugin, validate documentation code, shell script testing in docs, python snippet verification, documentation-testing, markdown-validation

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