pydoclint
pydoclint is the go-to linter for making sure Python docstrings match the
code they describe, with
It checks arguments, return values, yields, raises, class attributes, and type hints in numpy, Google, and Sphinx styles, with a few minor deviations.
Full documentation: jsh9.github.io/pydoclint.
Table of Contents
- 1. Why pydoclint?
- 2. Installation
- 3. Usage
- 4. Style violation codes
- 5. Documentation map
1. Why pydoclint?
1.1. Docstrings that stay true to the code
A docstring that disagrees with its code is worse than none.
pydoclint catches the drift from everyday edits (a renamed argument, a new
raise, a changed return type, an undocumented class attribute) and reports
each one as a
precise violation.
1.2. Built for the age of AI-assisted coding
AI coding agents write "mostly correct" docstrings, but omissions and hallucinations inevitably happen. That's why a deterministic docstring linter matters more than ever:
- Docstrings are context for AI. A stale docstring misleads the next agent that reads it.
- Reduce AI token usage. Agents don't need to spend tokens checking docstrings by hand; pydoclint does it deterministically.
- Fast enough for every change. It takes only 3 seconds, even on huge codebases like numpy (200k+ lines of code, 1,600+ classes, ~12k functions/methods).
- Agents can fix what it reports. Violation messages are specific and actionable, so an agent can correct them without a human in the loop.
1.3. Highly configurable
pydoclint offers 30+ configuration options for you to fine-tune it to fit your team's conventions. It also offers a "baseline" mode to ease adoption in legacy codebases.
1.4. pydoclint vs Ruff's DOC rules
Ruff re-implements a small subset of pydoclint's rules. As of September 2026, Ruff still lacks many of pydoclint's features:
| pydoclint | Ruff (DOC rules) |
|
|---|---|---|
| Number of rules | 39 | 7 |
| Number of config options | 30+ | 2 |
| Checks type hints | ✅ | ❌ |
| Checks class attributes | ✅ | ❌ |
| Sphinx style support | ✅ | ❌ |
| "Baseline" mode | ✅ | ❌ |
| Docstring style mismatch check | ✅ | ❌ |
Therefore, we recommend using pydoclint to check docstrings and letting Ruff handle other lint rules.
1.5. How to adopt pydoclint?
If you write code manually, this documentation is a good place to start. If you use AI assistants to code, simply say:
Help me adopt pydoclint in my codebase. Read its documentation at https://jsh9.github.io/pydoclint
Additionally, it is highly recommended that you also adopt
format-docstring as a pre-commit
hook alongside pydoclint. format-docstring syncs argument types, default
values, return types, and class attribute types from your code into your
docstrings, which automatically fixes many (but not all) of the issues that
pydoclint would catch. Run format-docstring first (i.e., list it above
pydoclint in .pre-commit-config.yaml), so that pydoclint only reports
what's left to fix. format-docstring also standardizes docstring formatting
to reduce diffs.
Note: format-docstring writes default values into docstrings by default
(e.g., n : int, default=3), while pydoclint by default expects docstrings
without them. To make the two tools agree, set pydoclint's
--check-arg-defaults=True (or run format-docstring with
--include-arg-defaults=False).
Adopting pydoclint in an existing codebase? Use the "baseline" mode: run
pydoclint once with --baseline=<FILE> and --generate-baseline=True to
record all current violations, and from then on it only reports new ones. With
--auto-regenerate-baseline (on by default), the baseline file shrinks as you
fix old violations. See
the documentation on these options
for details.
pydocstyle (or the D rules in Ruff) is
recommended too, as it checks some style rules that pydoclint isn't designed
to cover.
2. Installation
To install only the native pydoclint tooling, run this command:
pip install pydoclint
To use pydoclint as a flake8 plugin, please run this command, which will also install flake8 to the current Python environment:
pip install pydoclint[flake8]
pydoclint requires Python 3.10 or newer.
3. Usage
3.1. As a native command line tool
pydoclint <FILE_OR_FOLDER>
Replace <FILE_OR_FOLDER> with the file/folder names you want, such as ..
3.2. As a flake8 plugin
Once you install pydoclint[flake8], you can run:
flake8 --select=DOC <FILE_OR_FOLDER>
If you don't include --select=DOC in your command, flake8 will also run
other built-in flake8 linters on your code.
3.3. Native vs flake8
Should you use pydoclint as a native command line tool or a flake8 plugin? Here's a comparison:
| Pros | Cons | |
|---|---|---|
| Native tool | Slightly faster; supports "baseline"; supports inline # noqa |
No project-wide ignore list for violation codes (inline # noqa only) |
| flake8 plugin | Supports inline or project-wide omission | Slightly slower because other flake8 plugins are run together |
Tip: In native mode you can suppress DOC violations inline with
# noqa: DOCxxx. Use the--native-mode-noqa-locationoption (valid values: "docstring" or "definition") to decide whether the comment lives on the definition line or at the end of the docstring (after the triple quotes).
3.4. As a pre-commit hook
pydoclint can be used as a pre-commit hook, either in native mode or as a flake8 plugin.
To use it, put the following in your .pre-commit-config.yaml file:
3.4.1. Native mode
- repo: https://github.com/jsh9/pydoclint
rev: <latest_tag>
hooks:
- id: pydoclint
args: [--style=google, --check-return-types=False]
(Replace <latest_tag> with the latest release tag in
https://github.com/jsh9/pydoclint/releases)
3.4.2. As a flake8 plugin
- repo: https://github.com/jsh9/pydoclint
rev: <latest_tag>
hooks:
- id: pydoclint-flake8
args: [--style=google, --check-return-types=False]
3.5. How to configure pydoclint
Please read
How to configure pydoclint
for how to set options (on the command line, in pyproject.toml, or in
.pre-commit-config.yaml), and
Configuration options
for the full list.
3.6. How to ignore certain violations
Please read this page: How to ignore certain violations
3.7. Additional tips, tricks, and pitfalls
3.7.1. How to not document certain functions?
If you don't write any docstring for a function, pydoclint will not check it.
Also, if you write a docstring with only a description (without the argument
section, the return section, etc.), pydoclint will not check this docstring,
because the --skip-checking-short-docstrings is True by default. (You can
set it to False.)
3.7.2. Pitfall: type hints and default values
pydoclint compares type hints in docstrings with those in the function
signature verbatim. For example, if the signature says int | None, the
docstring should also say int | None (not Optional[int] or
int, optional).
Default values follow the --check-arg-defaults option:
- By default (
False), leave default values out of docstrings: writen : int, notn : int, default=3. - If set to
True, default values are required, in thedefault=...form (e.g.,n : int, default=3), and are checked against the signature. (This only applies to numpy and Google styles.)
These are deliberate deviations from the official docstring style guides, for unambiguity and speed. See minor style deviations for the details, and notes on writing type hints for the rationale.
4. Style violation codes
pydoclint currently has 7 categories of style violation codes:
DOC0xx: Docstring parsing issuesDOC1xx: Violations about input argumentsDOC2xx: Violations about return argument(s)DOC3xx: Violations about class docstring and class constructorDOC4xx: Violations about "yield" statementsDOC5xx: Violations about "raise" and "assert" statementsDOC6xx: Violations about class attributes
For detailed explanations of each violation code, please read this page: pydoclint style violation codes.
5. Documentation map
Every page of the full documentation:
Configuration
- How to configure pydoclint:
setting options on the command line, in
pyproject.toml, or in.pre-commit-config.yaml - Configuration options: every option, with its default value
- How to ignore certain violations:
inline
# noqacomments, in native mode, with flake8, and with Ruff
Reference
- Style violation codes:
what each
DOCxxxcode means - Minor style deviations: where pydoclint differs from the numpy, Google, and Sphinx style guides
- Docstring style mismatch (
DOC003): how pydoclint detects the style of a docstring
Guides
FAQ and limitations
- Notes for users: cases pydoclint is not designed to handle, notes on type hints, and editor integration
Contributing
- Notes for developers: if you'd like to contribute to pydoclint, thank you! This guide helps you get familiar with the code base.
1 maintainer
Metadata
1 maintainer
Release files for pydoclint 0.10.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| pydoclint-0.10.1.tar.gz | 228.6 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| pydoclint-0.10.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 322.1 kB
Release files / pydoclint-0.10.1.tar.gz
| Download URL | pydoclint-0.10.1.tar.gz |
|---|---|
| Size | 228.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
baa2ec9a1d1d60fbcf56fd56d75fbf37b426dfb620a04696ab3365025f44749c
|
|
BLAKE2b-256 checksum How to use checksums |
7601af79b4a9f6288fddd8503ffeb544b15db1f648dfbaa992dbc98159a04805
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / pydoclint-0.10.1-py3-none-any.whl
| Download URL | pydoclint-0.10.1-py3-none-any.whl |
|---|---|
| Size | 93.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e78be46fb82fa8068d16a5a8e8b17d11835d1a809b2702a2d0761801e956e97a
|
|
BLAKE2b-256 checksum How to use checksums |
33506ea5e79c1df40aa1cee86a0cc2e1cece6eb1c5dc72e77acbd165a273be3a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
