---
id: restructuredtext-lint
version: "2.0.2"
license: UNLICENSE
license_treatment: permissive
maintenance: aging
---

# restructuredtext-lint — reStructuredText linter

License: permissive · Maintenance: aging · Downloads: 17.1M/mo

## What it is and what it does

restructuredtext-lint checks reStructuredText files for structural violations before they are uploaded to PyPI or deployed. It wraps docutils parsing and exposes both a Python API (lint() and lint_file() functions) and a command-line tool (rst-lint) that report errors with line numbers, severity levels, and descriptive messages. Each error includes metadata like source file, error type (INFO/WARNING/ERROR/SEVERE), and the full context where the problem occurred.

The package was created to catch reST formatting issues locally rather than discovering them after publishing. It supports prepending content via rst_prolog for testing with substitutions, filtering by error severity, and output in text or JSON format. Custom directives and roles can be registered via docutils' extension mechanism, though Sphinx-specific customizations require manual registration due to parser differences.

Use it for:

- Validate README.rst and other documentation files before pushing to PyPI or a repository
- Integrate linting into CI/CD pipelines to catch reStructuredText errors early
- Check documentation consistency in projects using Sphinx or docutils
- Programmatically lint reST content in build scripts or documentation generators
- Detect title underlines, hyperlink issues, and lexer problems that would fail on PyPI

## Worth the install?

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

Lints reStructuredText documents for structural errors and returns a list of violations with line numbers, severity levels, and messages.

Yes, if you work with reStructuredText documentation or publish to PyPI. The tool solves a real problem—catching formatting errors before upload—with low install friction and no security vulnerabilities. The aging maintenance status (264 days since release) is a minor concern for a stable linter, but the unarchived repository and active last commit suggest it is not abandoned. Install if you need local validation; skip if you only use Markdown or have no reStructuredText workflow.

## Install

pip install restructuredtext-lint
uv add restructuredtext-lint
poetry add restructuredtext-lint

## Installing restructuredtext-lint

Before you install: Low friction installation with a single runtime dependency (docutils). Package is aging (264 days since last release) but repository remains active and unarchived with a modest user base.

License in practice: Released to public domain under UNLICENSE, permitting unrestricted use, modification, and distribution with no attribution or warranty obligations.

Quickstart:

pip install restructuredtext-lint

import restructuredtext_lint
errors = restructuredtext_lint.lint("Hello World\n=======\n")
print(errors[0].message if errors else "No errors")

Verify before relying:

- Whether Python version support is truly unspecified or simply undocumented in the fact sheet
- Current state of Sphinx directive/role compatibility beyond the known limitations mentioned in docs

## Package facts

- License: UNLICENSE (permissive)
- Python support: unspecified
- Install friction: low
- Maintenance: aging
- Downloads: 17.1M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

restructuredtext linter, rst syntax checker, rest document validation, sphinx documentation linter, rst error detection, restructured text lint tool, pypi readme validator, documentation-validation, cli-tool

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