---
id: blacken-docs
version: "1.20.0"
license: MIT
license_treatment: permissive
maintenance: active
---

# blacken-docs — Run Black on Python code blocks in documentation files.

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

## What it is and what it does

blacken-docs is a command-line tool that runs Black's code formatter on Python code blocks found within documentation files. It recognizes Python code in Markdown fenced blocks (```python and ```pycon), reStructuredText code-block directives, LaTeX minted and pycode environments, and Python docstrings. The tool rewrites files in place and exits with a non-zero status if any changes were made, making it suitable for CI/CD pipelines and pre-commit hooks.

The package depends solely on black and is designed to keep documentation examples in sync with your project's code style. It supports Black's key options (line length, target version, string normalization, preview mode) and adds its own flags for dry-run checking, error suppression, and optional reStructuredText literal-block formatting. It does not recurse directories—you provide explicit file paths or use shell globbing and pre-commit integration to apply it across many files.

Use it for:

- Enforce consistent code style in README and API documentation examples alongside your main codebase formatting.
- Integrate into pre-commit hooks to automatically reformat code blocks in pull requests before commit.
- Verify documentation code blocks are syntactically valid and properly formatted as part of CI checks.
- Reformat Python code examples embedded in docstrings when refactoring or upgrading Black versions.
- Maintain LaTeX documentation with minted code blocks in a consistent style with your project's Black config.

## Worth the install?

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

Applies Black code formatting to Python code blocks embedded in documentation files (Markdown, reStructuredText, LaTeX) and Python docstrings.

Yes. This is a lightweight, actively maintained tool with no security vulnerabilities and a single stable dependency. Install it if you maintain documentation with embedded Python code and want to keep those examples formatted consistently with Black. The pre-commit integration makes it a natural fit for projects already using Black.

## Install

pip install blacken-docs
uv add blacken-docs
poetry add blacken-docs

## Installing blacken-docs

Before you install: Low friction: single runtime dependency on black, pure Python wheel, actively maintained with recent releases. Supports Python 3.9 to 3.14.

License in practice: MIT license permits unrestricted use, modification, and distribution with minimal restrictions—suitable for any project type.

Quickstart:

pip install blacken-docs
blacken-docs README.rst

# Or in a pre-commit hook:
# Add to .pre-commit-config.yaml:
# - repo: https://github.com/adamchainz/blacken-docs
#   rev: "1.20.0"
#   hooks:
#   - id: blacken-docs
#     additional_dependencies:
#     - black==22.12.0

Requires black 22.1.0 or later; best practice is to pin black version in pre-commit additional_dependencies to avoid format drift.

Verify before relying:

- Whether the tool correctly handles edge cases in mixed-format documentation (e.g., nested code blocks or unusual indentation).
- Performance characteristics when processing large documentation sets or files with many code blocks.

## Package facts

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

## Tags

format python code in docs, black code formatter documentation, reformat code blocks markdown, docstring code formatting, documentation code style, pre-commit black integration, rst python block formatter, code-formatter, documentation-tools, pre-commit

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