docformatter

What it is and what it does

docformatter is a command-line tool and library that automatically reformats Python docstrings to follow PEP 257 conventions. It enforces consistent triple-quote usage, proper line breaks between summary and description, correct placement of closing quotes, and removal of trailing whitespace. It also supports Sphinx and Epytext field list styles and can be configured to work alongside black for code formatting.

The tool is designed for developers and teams who want to standardize docstring formatting across a codebase without manual editing. It works as both a standalone CLI (with --in-place file modification) and as a library that can be integrated into linting pipelines. The package has minimal dependencies and supports current Python versions, making it straightforward to add to existing projects.

Use it for:

• Enforce PEP 257 docstring standards across a team's Python codebase automatically.
• Integrate into pre-commit hooks or CI/CD pipelines to catch docstring formatting issues before merge.
• Reformat legacy codebases with inconsistent docstring styles to a uniform standard.
• Work alongside black to ensure both code and docstring formatting align with project conventions.
• Configure project-wide docstring rules via pyproject.toml for reproducible formatting.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Automatically formats Python docstrings to comply with PEP 257 conventions, including proper quote usage, line breaks, and field list formatting.

Yes. docformatter is actively maintained, has no known vulnerabilities, minimal dependencies, and solves a real problem in code standardization. It integrates well with existing Python tooling and is permissively licensed. Install it if your team values consistent docstring formatting or you need PEP 257 compliance automation.

Install

docformatter on PyPI

pip install docformatter

uv add docformatter

poetry add docformatter

Installing docformatter

Before you install

Low friction: pure Python wheel with a single runtime dependency (charset_normalizer). Active maintenance with a recent release (108 days ago) and ongoing commits. Supports modern Python versions (3.10–3.14) and PyPy.

License in practice

Licensed under Expat (MIT), a permissive license that allows commercial and private use with minimal restrictions. No licensing barriers to adoption.

Quickstart

pip install docformatter

# Format a file in-place
docformatter --in-place example.py

# Or use as a library
from docformatter import format_docstring
formatted = format_docstring('', '"""Original docstring."""')

Requires Python 3.10 or later; Python < 3.11 users need the optional tomli extra to use pyproject.toml configuration.

Verify before relying

• Whether the package handles all Sphinx and Epytext field list styles or only a subset.
• Performance characteristics when formatting large codebases or deeply nested docstrings.
• Compatibility guarantees with other formatters beyond black when using --black mode.

Package facts

Evidence: docformatter-1.7.8-py3-none-any.whl

Keywords: PEP 257, pep257, style, formatter, docstrings

Tags

More Quality Assurance packages