---
id: docformatter
version: "1.7.8"
license: Expat
license_treatment: permissive
maintenance: active
---

# docformatter — Formats docstrings to follow PEP 257

License: permissive · Maintenance: active · Downloads: 1.5M/mo

## 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 above — 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

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

- License: Expat (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 1.5M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

docstring formatter pep 257, python docstring style, automatic docstring formatting, pep 257 compliance tool, docstring linter, code documentation formatter, docstring standardizer, code-quality, documentation, formatter

[View on SkillFed](https://skillfed.io/packages/docformatter) · [View on PyPI](https://pypi.org/project/docformatter/)