---
id: flake8-rst-docstrings
version: "0.4.0"
license: MIT
license_treatment: permissive
maintenance: active
---

# flake8-rst-docstrings — Python docstring reStructuredText (RST) validator for flake8

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

## What it is and what it does

This is a flake8 plugin that integrates reStructuredText validation into your code linting workflow. It parses docstrings in Python files and checks them for RST markup errors using the docutils library, reporting issues with codes like RST201–RST220 for warnings, RST301–RST308 for major errors, and RST401–RST499 for severe errors. It complements pydocstyle-based checks (which validate docstring presence and PEP 257 conventions) by focusing specifically on the markup quality of docstring content.

The plugin runs as part of flake8, automatically detecting RST violations and reporting them with line numbers. It maps docutils severity levels to flake8 codes, so you can selectively enable or ignore specific RST error categories. Configuration options let you register custom Sphinx directives and roles to avoid false positives in projects using Sphinx extensions.

Use it for:

- Enforce consistent reStructuredText formatting in docstrings across a project during CI/CD linting.
- Catch RST syntax errors (malformed tables, unclosed markup, undefined substitutions) before documentation generation.
- Validate docstrings in Sphinx-documented projects by configuring recognized directives and roles.
- Combine with flake8-docstrings to check both docstring presence (PEP 257) and RST markup validity.
- Detect inline markup errors like mismatched emphasis or literal block issues in docstring content.

## Worth the install?

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

A flake8 plugin that validates Python docstrings as reStructuredText markup, catching RST syntax errors and formatting issues in docstring content.

Yes. The plugin is actively maintained, has no known vulnerabilities, installs with low friction, and fills a specific gap: validating RST markup in docstrings. Install it if your project uses reStructuredText docstrings and you want to catch markup errors early. Pair it with flake8-docstrings for comprehensive docstring linting.

## Install

pip install flake8-rst-docstrings
uv add flake8-rst-docstrings
poetry add flake8-rst-docstrings

## Installing flake8-rst-docstrings

Before you install: Low friction installation with three runtime dependencies (flake8, restructuredtext_lint, pygments). Actively maintained with a recent release in October 2025 and ongoing commits through August 2026.

License in practice: MIT licensed, permissive terms—you can use, modify, and distribute the package freely in commercial and private projects without restriction.

Quickstart:

pip install flake8-rst-docstrings

flake8 example.py
# or to see only RST violations:
flake8 --select RST example.py

Requires Python 3.9 or later.

Verify before relying:

- Whether false positives are common when using Sphinx extensions without explicit configuration.
- Performance impact on large codebases with many docstrings.

## Package facts

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

## Tags

flake8 docstring validation, rst docstring linter, restructuredtext syntax checker, docstring markup validation, flake8 rst plugin, python docstring rst lint, docstring-linting, rst-validation, flake8-plugin

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