Install & Compatibility
Where this runs
tested against v2.0.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.116s · 22.2MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.8s · import 0.106s · 23MB
21MB installed
● package 21MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
lint
✓ from restructuredtext_lint import lint
lint_file
✓ from restructuredtext_lint.file_lint import lint_file
✗ from restructuredtext_lint.lint import lint_file
The import path for `lint_file` changed in version 2.0.0. It was moved from the top-level `lint` module to `file_lint`.
This quickstart demonstrates how to use `restructuredtext-lint` to check a string for reStructuredText syntax errors and warnings. It iterates through the detected errors, printing their type, line number, and message. It also shows the general approach for linting files.
from restructuredtext_lint import lint
rst_content = '''
My Document
===========
.. This is a comment
This is a paragraph with some `broken
.. bad_directive::
An error will be reported above.
'''
errors = lint(rst_content)
if errors:
print(f"Found {len(errors)} linting issues:")
for error in errors:
print(f" [{error.type.upper()}] Line {error.line}: {error.message}")
else:
print("No linting issues found.")
# To lint a file:
# from restructuredtext_lint.file_lint import lint_file
# errors_from_file = lint_file('path/to/your/file.rst')
rst-lint --version
Debug
Known issues
breakingThe import path for `lint_file` changed significantly in version 2.0.0, moving from the main `lint` module to a dedicated `file_lint` module.fixUpdate your import statements: change `from restructuredtext_lint.lint import lint_file` to `from restructuredtext_lint.file_lint import lint_file`.
affects: 2.0.0 and later
breakingVersion 2.x and above of `restructuredtext-lint` are exclusively Python 3 compatible. Earlier 1.x versions supported Python 2.fixEnsure your environment is running Python 3. For projects still requiring Python 2, you must pin the dependency to `restructuredtext-lint<2.0.0`.
affects: 2.0.0 and later
gotchaLinting results (errors) can have different severity `type` values, including 'info', 'warning', 'error', and 'severe'. Consumers of the library must handle these distinctions if they wish to filter or prioritize issues.fixWhen processing the list of `errors`, inspect the `error.type` attribute to filter or categorize issues according to your requirements. For example, `if error.type == 'error': ...`.
affects: All versions
gotchaIn version 2.0.0, `lint_file` briefly switched its parsing backend from `docutils` to `sphinx`. This was reverted in 2.0.1, restoring `docutils` as the backend. This might cause subtle behavioral differences or break Sphinx-specific directives if upgrading *only* to 2.0.0, then later upgrading to 2.0.1+.fixIf relying on `lint_file` and specific Sphinx extensions or features, be aware that 2.0.0 was the only version in the 2.x series to explicitly support a Sphinx backend; subsequent versions reverted to `docutils`. Test thoroughly when upgrading through these specific point releases.
affects: 2.0.0, 2.0.1 and later
Upgrade
Version history
2.0.2latest on PyPI · released Nov 23, 2025
Audit
Dependencies
docutilsrequiredCore dependency for parsing reStructuredText documents.