doc8

library2.0.0pypypi✓ verified 23d ago

doc8 is an opinionated style checker for reStructuredText (RST) based documentation, including Sphinx-compatible projects. It helps enforce style guidelines for `.rst` and plain text files. The library is currently at version 2.0.0, with a release cadence that addresses Python compatibility, bugfixes, and minor enhancements.

testing

pip install doc8

github ↗package ↗docs ↗

INSTALL

IMPORT

SIG · DOC8

doc8

testingpythonv2.0.0

Install

2.6s avg

Import

214ms

Disk

30MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.0.0 · 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

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.220s · 31.5MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 2.6s · import 0.208s · 32MB

30MB installed

● package 30MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

doc8

✓ from doc8 import doc8

Can be used programmatically by importing the main function.

Run doc8 against a directory containing your reStructuredText documentation to check for style violations.

pip install doc8 doc8 path/to/your/docs

doc8 --version

Debug

Known issues

breakingVersion 2.0.0 and newer explicitly require Python 3.10 or higher. Users on older Python versions (e.g., 3.9 or below) must upgrade their Python environment to use the latest doc8.

fix

Upgrade your Python environment to 3.10 or newer. For older Python versions, use doc8 < 2.0.0, e.g., `pip install 'doc8<2.0.0'`.

affects: 2.0.0+

breakingSupport for Python 3.7 was removed in v1.1.1. Further, Python 3.6 support was dropped in v1.0.0, and Python 2.7/3.5 support in v0.9.0.

fix

Ensure your project's Python version meets the minimum requirements for the doc8 version you intend to use.

affects: 1.1.1+, 1.0.0+, 0.9.0+

gotchaConfiguration files have evolved. While `setup.cfg`, `doc8.ini`, `tox.ini`, and `.config/doc8.ini` are supported, `pyproject.toml` is the modern and preferred method for configuration. Ensure your configuration is correctly placed under a `[tool.doc8]` section in `pyproject.toml`.

fix

Migrate your configuration to `pyproject.toml` for future compatibility. Example configuration structures can be found in the official documentation.

affects: All versions with `pyproject.toml` support (0.9.0+)

gotchaThe `chardet` based input encoding detection was removed in v0.9.0, meaning `doc8` no longer attempts to automatically detect file encodings.

fix

Explicitly set the file encoding using the `--file-encoding` option if your documentation files are not UTF-8.

affects: 0.9.0+

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'doc8'

The `doc8` package is not installed in the Python environment being used, or the Python environment where `doc8` is installed is not the one being invoked by the command or IDE.

fix

Install `doc8` using pip: `pip install doc8`. If using an IDE like VS Code, ensure the correct Python interpreter (where `doc8` is installed) is selected, or specify the executable path in the IDE's settings.

D001 Line too long

`doc8` has detected a line that exceeds the maximum allowed character length, which defaults to 79 characters.

fix

Either refactor the line to be shorter than the maximum length, or configure `doc8` to allow a longer line length using the `--max-line-length` option (e.g., `doc8 --max-line-length 120`) or by setting `max-line-length` in a configuration file (e.g., `doc8.ini`, `pyproject.toml`).

D004 Found literal carriage return

This error typically occurs on Windows systems where files use CRLF (Carriage Return Line Feed) line endings, but `doc8` expects LF (Line Feed) line endings, common in Unix-like systems.

fix

Configure your text editor or version control system to use LF line endings for reStructuredText files. Alternatively, ignore this specific error using the `--ignore D004` command-line option or by adding `ignore=D004` to your `doc8` configuration file.

doc8 ignores '--config pyproject.toml'

When specifying a configuration file like `pyproject.toml` (or `setup.cfg`), `doc8` may fail to load or correctly parse its settings, often due to missing `toml` parsing dependencies or issues with the configuration file's format or path, especially on newer Python versions.

fix

Ensure `toml` parsing libraries are available (e.g., `pip install toml`). Double-check the configuration file path and syntax, ensuring the `[tool.doc8]` section is correctly defined. If using an older Python version or encountering persistence issues, consider using an older configuration format like `doc8.ini` or passing arguments directly via the command line.

Upgrade

Version history

2.0.0latest on PyPI · released Jun 13, 2025

Audit

Dependencies

pythonrequiredRequires Python 3.10 or newer.

Agent activity

9 hits · last 30 days

node

Resources

githubhttps://github.com/pycqa/doc8 ↗

packagehttps://pypi.org/project/doc8/ ↗

docshttps://doc8.readthedocs.io ↗