Install & Compatibility
Where this runs
tested against v6.3.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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.460s · 19.5MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.7s · import 0.440s · 20MB
18MB installed
● package 18MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
run_check
✓ import pydocstyle
# errors = pydocstyle.run_check(paths=['your_file.py'])
Pydocstyle is primarily a command-line tool. Programmatic usage often involves internal APIs like `pydocstyle.run_check` for checking files directly or `pydocstyle.checker.Checker` for more fine-grained control. The most common use case is via the CLI.
Pydocstyle is typically used as a command-line tool. Create a Python file (e.g., `example.py`) with docstrings, then run pydocstyle against it. The `--ignore` or `--select` options allow for fine-grained control over which docstring style errors are reported.
import os
def my_function():
"""This is a sample function.
It returns a string.
"""
return "Hello"
# Save this to a file, e.g., `example.py`
# Then run from the command line:
# pydocstyle example.py
# You can also customize checks:
# pydocstyle --ignore=D100,D104 example.py
pydocstyle --version
Debug
Known issues
breakingThe Pydocstyle project is officially deprecated and no longer actively maintained. Users are strongly recommended to migrate to Ruff, which offers full parity with pydocstyle and active development.fixMigrate your project's docstring linting to Ruff. Consult the Ruff documentation for migration instructions.
affects: All versions, especially 6.3.0 onwards as it's the last release.
deprecatedConfiguration files named `.pep257` and section headers `[pep257]` are deprecated for backwards compatibility. Support for these will be removed in a future major version, which is unlikely to happen given the project's deprecation.fixUse configuration files like `setup.cfg`, `tox.ini`, `.pydocstyle`, `.pydocstylerc`, or `pyproject.toml` with `[pydocstyle]` or `[tool.pydocstyle]` sections.
affects: <6.0.0 (renamed from pep257 to pydocstyle), 6.x.x
gotchaWhen using Google or NumPy docstring conventions, pydocstyle might incorrectly default to checking for one style over the other if section names (e.g., 'Returns', 'Yields') overlap. This can lead to false positives or missed errors.fixCarefully review results when using Google or NumPy conventions. You may need to manually ignore specific errors (`--ignore`) or explicitly select convention checks (`--convention=numpy` or `--convention=google`) to align with your project's chosen style.
affects: All 6.x.x versions using Google or NumPy conventions.
gotchaSupport for TOML configuration files (e.g., `pyproject.toml`) is only enabled if the `toml` Python package is installed. If it's missing, pydocstyle will not recognize your TOML configuration.fixInstall pydocstyle with the `toml` extra: `pip install pydocstyle[toml]`.
affects: All 6.x.x versions when using TOML configs.
Errors
Common errors & fixes
D100: Missing docstring in public module
A public Python module, class, or function is missing a docstring, violating the specified docstring convention (by default, PEP 257).
fixAdd a proper docstring to the undocumented public module, class, or function. Alternatively, configure pydocstyle to ignore this specific error code using `--ignore=D100` in the command line or a configuration file.
D202: No blank lines allowed after function docstring (found 1)
This error often occurs when pydocstyle is used with code formatters like Black, which, in some versions, introduce a blank line after a function docstring, conflicting with pydocstyle's requirement for no blank lines in that position.
fixConfigure pydocstyle to ignore the D202 error code by adding `--ignore=D202` to your command line arguments or `ignore = D202` to your configuration file (e.g., `setup.cfg` or `pyproject.toml`).
ModuleNotFoundError: No module named 'pydocstyle'
The `pydocstyle` package is not installed in the current Python environment or is not accessible in the `PYTHONPATH`.
fixInstall pydocstyle using pip: `pip install pydocstyle`. Ensure you are in the correct Python virtual environment if you are using one.
The Pydocstyle project is officially deprecated and no longer actively maintained.
This is an official announcement from the project maintainers indicating that pydocstyle is no longer under active development.
fixConsider migrating your docstring linting to an actively maintained alternative like Ruff, which provides full parity with pydocstyle and ongoing development.
toml configuration file support is only enabled if the `toml` python package is installed.
You are attempting to use a `pyproject.toml` file for pydocstyle configuration, but the optional `toml` dependency, which is required for TOML support, is not installed.
fixInstall pydocstyle with the `toml` extra: `pip install pydocstyle[toml]`.
Upgrade
Version history
6.3.0latest on PyPI · released Jan 17, 2023
Audit
Dependencies
pythonrequiredRuntime dependency for the library.
tomloptionalRequired for parsing TOML configuration files (e.g., pyproject.toml). Install with `pip install pydocstyle[toml]`.