---
id: pydocstringformatter
version: "1.0.0"
license: MIT
license_treatment: permissive
maintenance: active
---

# pydocstringformatter — A tool to automatically format Python docstrings that tries to follow recommendations from PEP 8 and PEP 257.

License: permissive · Maintenance: active · Downloads: 172.2K/mo

## What it is and what it does

Pydocstringformatter is a command-line tool that reads Python source files and automatically reformats their docstrings to align with PEP 8 and PEP 257 style guidelines. It was created by contributors to the pylint project to address gaps in existing formatters, with a design philosophy that makes some of the more contentious PEP requirements optional rather than mandatory.

The tool handles common docstring issues: fixing quote styles, capitalizing summaries, normalizing whitespace, enforcing period terminators, and aligning multi-line docstrings. It supports multiple style guides simultaneously (e.g., pep257 and numpydoc), reads configuration from pyproject.toml, and integrates with pre-commit workflows. With zero runtime dependencies and active maintenance, it's designed as a lightweight addition to Python development toolchains.

Use it for:

- Enforce consistent docstring formatting across a team or open-source project without manual review.
- Integrate into CI/CD pipelines via pre-commit hooks to catch docstring style violations before merge.
- Reformat legacy codebases to meet modern PEP 257 standards in bulk.
- Configure project-specific docstring rules in pyproject.toml and apply them uniformly.
- Use as a linting step alongside pylint to maintain documentation quality.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Automatically formats Python docstrings to comply with PEP 8 and PEP 257 recommendations, with support for multiple style guides and configurable strictness.

Yes. The package is actively maintained, has no dependencies, requires only Python 3.11+, carries no known vulnerabilities, and solves a real problem in code quality enforcement. Install it if your team wants automated, configurable docstring formatting aligned with PEP standards.

## Install

pip install pydocstringformatter
uv add pydocstringformatter
poetry add pydocstringformatter

## Installing pydocstringformatter

Before you install: Low friction—pure Python wheel with no runtime dependencies. Actively maintained as of 41 days ago with recent commits and a stable release cycle.

License in practice: MIT license is permissive; you can use, modify, and distribute this package freely in commercial and private projects with minimal restrictions.

Quickstart:

pip install pydocstringformatter

pydocstringformatter myfile.py

# Or with configuration in pyproject.toml:
[tool.pydocstringformatter]
write = true
style = "pep257"

Requires Python 3.11 or later.

Verify before relying:

- Whether the tool can be integrated into CI/CD pipelines beyond pre-commit hooks.
- Performance characteristics when run on large codebases or projects with thousands of files.
- How the tool handles edge cases in docstrings with complex formatting or non-ASCII characters.

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 172.2K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

python docstring formatter, pep 257 docstring auto-format, docstring style checker, automatic docstring linting, pep 8 compliance tool, docstring formatting cli, code-quality, docstring-formatting, pep-compliance

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