pydoclint

pydoclint is the go-to linter for making sure Python docstrings match the code they describe, with monthly downloads.

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?
  • 1.1. Docstrings that stay true to the code
  • 1.2. Built for the age of AI-assisted coding
  • 1.3. Highly configurable
  • 1.4. pydoclint vs Ruff's DOC rules
  • 1.5. How to adopt pydoclint?
• 2. Installation
• 3. Usage
  • 3.1. As a native command line tool
  • 3.2. As a flake8 plugin
  • 3.3. Native vs flake8
  • 3.4. As a pre-commit hook
    • 3.4.1. Native mode
    • 3.4.2. As a flake8 plugin
  • 3.5. How to configure pydoclint
  • 3.6. How to ignore certain violations
  • 3.7. Additional tips, tricks, and pitfalls
    • 3.7.1. How to not document certain functions?
    • 3.7.2. Pitfall: type hints and default values
• 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:

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:

Tip: In native mode you can suppress DOC violations inline with # noqa: DOCxxx. Use the --native-mode-noqa-location option (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: write n : int, not n : int, default=3.
• If set to True, default values are required, in the default=... 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 issues
• DOC1xx: Violations about input arguments
• DOC2xx: Violations about return argument(s)
• DOC3xx: Violations about class docstring and class constructor
• DOC4xx: Violations about "yield" statements
• DOC5xx: Violations about "raise" and "assert" statements
• DOC6xx: 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 # noqa comments, in native mode, with flake8, and with Ruff

Reference

• Style violation codes: what each DOCxxx code 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

• Checking class attributes
• Names with leading underscores
• Generator vs Iterator (DOC405)

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.