# docformatter: making docstrings match PEP 257 without hand editing

> docformatter is a small Python tool that rewrites docstrings to follow a subset of PEP 257, handling indentation, quote style, summary lines and closing quote placement, with an option to stay compatible with black and support for Epytext and Sphinx field lists. It is part of the PyCQA family of Python code quality tools.

**PyCQA/docformatter** — Formats docstrings to follow PEP 257

- Repository: https://github.com/PyCQA/docformatter
- Website: https://pypi.python.org/pypi/docformatter
- Stars: 598 · Forks: 97
- Language: Python
- License: MIT
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/pycqa-docformatter

## The subset of PEP 257, quoted from the standard

docformatter formats docstrings to follow PEP 257, and the readme is careful to say a subset of the conventions rather than the whole standard. It then quotes the relevant items from PEP 257 directly, which is a good way to understand the tool's scope.

For consistency, always use triple double quotes around docstrings. Triple quotes are used even though the string fits on one line. Multi-line docstrings consist of a summary line just like a one-line docstring, followed by a blank line, followed by a more elaborate description. Unless the entire docstring fits on a line, place the closing quotes on a line by themselves.

Those four rules are what the formatter is built around, and they are all mechanical. That is the point of the tool. A docstring that starts on the line above the function, uses single quotes, has its summary wrapped across two lines, or closes its quotes on the content line is a style difference a human reviewer will not flag and a linter will. docformatter makes the mechanical part automatic so a reviewer only looks at the words.

It also handles some of the PEP 8 conventions. The one named is about not writing string literals that rely on significant trailing whitespace, since such trailing whitespace is visually indistinguishable and some editors, or more recently reindent.py, will trim it. A formatter that moves docstrings around has to deal with that, because a rewrap can silently change the content of a docstring that was relying on trailing spaces.

The project is MIT licensed, published on PyPI as docformatter, with the latest release v1.7.8 from 2026-04-21, and the last push was on 2026-10-16.

## Installing it, and the tomli wrinkle on older Pythons

Installation is a pip install, and the readme then covers the two variations you are likely to need.

```
    $ pip install --upgrade docformatter
```

If you want to configure docformatter through pyproject.toml and you are on Python below 3.11, there is an extra to install:

```
    $ pip install --upgrade docformatter[tomli]
```

With Python 3.11 and above, tomllib from the standard library is used instead, so the dependency is unnecessary there. The pyproject.toml confirms the shape of this, with tomli declared as an optional dependency pinned to version 2.0.0 for Python below 3.11, and charset_normalizer at 3.0.0 as a required dependency. The Python floor is 3.10.

There is also a way to install a release candidate, or any other tag, straight from the repository:

```
    $ pip install git+https://github.com/PyCQA/docformatter.git@<RC_TAG>
```

The tag naming is specified, so the release candidate tags have the format v1.6.0-rc1, and the readme notes that release candidates will also be made available as a GitHub Release.

The package is built with poetry, with the source under a src layout, and the classifiers list Python 3.10 through 3.14, with both PyPy and CPython implementations declared. The licence is recorded as Expat, which is the MIT licence under its SPDX name, and the maintainer listed in the pyproject is Doyle Rowland, with the original author as Steven Myint.

The development tooling is also poetry-grouped, which is a tidy arrangement: a dev group with Sphinx, tox and twine, a testing group with pytest, pytest-cov, pytest-order, coverage and mock, and a linting group with autopep8, black, isort, mypy, pycodestyle, pydocstyle, pylint and rstcheck. The presence of pydocstyle and rstcheck in the linting group is the interesting part, because those are the tools that would complain about the very conventions docformatter is normalising to.

## What the formatter actually changes in a file

The readme demonstrates the transformation with a before and after, and it is worth reading closely because it shows the tool's judgement rather than a list of flags.

The input has a module docstring with stray leading whitespace after the opening quotes and the closing quotes stuck to the end of the text, a function using single triple quotes with a leading blank line inside and the closing quotes on their own line, a one-line docstring without a closing period, and a two-line docstring where the summary runs onto the next line:

```
    """   Here are some examples.

        This module docstring should be dedented."""


    def factorial(x):
        '''

        Return x factorial.

        This uses math.factorial.

        '''
        import math
        return math.factorial(x)


    def print_factorial(x):
        """Print x factorial"""
        print(factorial(x))
```

And the output is the same code with the module docstring dedented and its closing quotes on their own line, the function docstring converted to triple double quotes with the leading blank line removed, the one-line docstring given a closing period, and the two-line summary joined into a single line:

```
    """Here are some examples.

    This module docstring should be dedented.
    """

    def factorial(x):
        """Return x factorial.

        This uses math.factorial.
        """
        import math
        return math.factorial(x)


    def print_factorial(x):
        """Print x factorial."""
        print(factorial(x))
```

Two of those changes are worth pausing on. The first is that a docstring whose summary wrapped onto a second line gets joined, which means the formatter is rewrapping text and not only moving it around. The second is the added full stop on a one-line docstring, which is a content change rather than a whitespace change, and which means a team that does not use terminal punctuation on one-liners will get a diff they did not ask for.

The transformation is applied with:

```
    $ docformatter --in-place example.py
```

The in-place flag is the one to reach for in a script, and without it the formatter writes to standard output, which is the useful behaviour for piping into a diff or for checking a single file before committing to the change.

## Pre-commit hooks, tox and the rest of the repository

The repository is a small, well-organised Python project, and the layout tells you how the project expects to be used.

The top level is a src layout with the package under src, a tests directory, a docs directory, and the standard metadata: pyproject.toml, poetry.lock, tox.ini, a CHANGELOG, an AUTHORS file, and a LICENSE. The licence is MIT.

Two files are worth noticing for what they say about intended usage. There is a .pre-commit-config.yaml and a .pre-commit-hooks.yaml, which is the pair that lets a project consume docformatter as a pre-commit hook rather than as a manual step. That is the most common way a team ends up with a consistent docstring style, and the fact that the project ships the hook definition itself rather than only documenting the command is a deliberate distribution choice. There is also a .sourcery.yaml, which is a configuration for the Sourcery code review service.

The tox.ini is the multi-environment test runner, which pairs with the poetry dependency groups. The testing group is pytest with pytest-cov for coverage, pytest-order for ordering dependent tests, and mock, and the linting group is where the style tools live, including the pydocstyle and rstcheck entries that would otherwise disagree with what docformatter produces.

The docs directory is built with Sphinx, which is the documentation tool whose field list style docformatter explicitly supports, so the tool and the documentation generator are designed to work together rather than to fight.

The readme also has an Issues section, and the final line of it is truncated in the source, which tells you that the project has an issue tracker policy worth reading on the site. And the release history shows a steady maintenance cadence, with v1.7.6 and v1.7.7 in May 2025 and v1.7.8 in April 2026, so the tool is being kept current with new Python versions rather than left to rot.

The badges at the top of the readme also cover the packaging side: a PyPI version badge, a licence badge, a Python versions badge, a format badge, a diff coverage badge and a pre-release badge, which between them say the package is published, tested against several Python versions and covered by a diff-aware coverage measurement.

## Compatibility with black, and the field list handling

Two features determine whether docformatter can live alongside the rest of your toolchain.

The first is black compatibility. docformatter formats docstrings compatible with black when passed the --black option. That is not a minor detail, because black and docformatter both rewrite code and can disagree about line length, and a formatter that undoes the work of another is unusable in a repository that runs both. The readme badges place them side by side, with the code section listing black and isort and the docstring section listing docformatter, which is a visual statement that they are meant to coexist.

The second is field list handling. docformatter formats field lists that use Epytext or Sphinx styles. A field list is the structured part of a docstring, the parameter descriptions and the notes and references sections, and in Sphinx style those fields have their own indentation rules that a naive rewrapper would destroy. Handling them is what stops the tool from mangling the structured documentation in a project that uses Sphinx.

The readme points to the full documentation at read-the-docs, and specifically to the requirements section for a more detailed discussion of PEP 257 and other requirements. That pointer is the one to read before enabling the tool on a large codebase, because the requirements section is where the exact subset and its interaction with the other conventions is spelled out.

The remaining readme content is smaller. There is a Marketing section asking users to add badges to their project's README to show which docstring style they use, with badge blocks for the docformatter style and for the Sphinx, numpy and Google styles, which is a nice illustration that docformatter is one convention among several rather than the only one. And there is an Assistance section pointing at an IRC channel on Libera.Chat in the docformatter room, while noting there is no docformatter channel on the Python Code Quality Discord server, where the general channel is the place to ask.

## Conclusion

Adopt docformatter if your team has a PEP 257 or PEP 8 docstring convention and wants it applied consistently across a codebase without a human touching each function, especially as a pre-commit hook. Do not adopt it if your project already settles docstring shape with another tool, and be careful that it normalises to its own subset of PEP 257 rather than to every convention, so a house style with a different summary line or field layout will fight it. Before you commit, run it on one file and read the diff, because docformatter moves content and rewraps it, and check that it agrees with the style of the surrounding code before you turn it on for a whole repository.

## FAQ

### What does docformatter do?

It automatically formats docstrings to follow a subset of the PEP 257 conventions, including always using triple double quotes, keeping a summary line at the start of a multi-line docstring, placing closing quotes on their own line when the docstring does not fit on one line, and removing significant trailing whitespace.

### How do I install docformatter?

With pip install --upgrade docformatter. If you want to configure it through pyproject.toml on Python below 3.11, install the tomli extra, since Python 3.11 and above uses tomllib from the standard library. A release candidate can be installed directly from the repository with a tag such as v1.6.0-rc1.

### Is docformatter compatible with black?

Yes, with the --black option docformatter formats docstrings in a way that is compatible with black. The readme badges list black and isort alongside docformatter for code, and docformatter for docstrings, indicating they are meant to be used together.

### Does docformatter handle Sphinx and numpy field lists?

It formats field lists that use Epytext or Sphinx styles, which is what stops the structured parameter and notes sections of a docstring being mangled by a rewrap. The readme points at the requirements section of the documentation for a fuller discussion of PEP 257 and the other requirements.

### How do I apply docformatter to a file?

Run docformatter --in-place example.py to rewrite the file. Without the in-place flag the formatted output goes to standard output, which is useful for reviewing the change before applying it.

## Sources

- [License: MIT](https://github.com/PyCQA/docformatter/blob/master/LICENSE)
- [Project website](https://pypi.python.org/pypi/docformatter)
- [PyCQA/docformatter on GitHub](https://github.com/PyCQA/docformatter)
- [README](https://github.com/PyCQA/docformatter/blob/master/README.md)
- [Releases](https://github.com/PyCQA/docformatter/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/pycqa-docformatter