---
id: docstrfmt
version: "2.2.0"
license: unclear
license_treatment: permissive
maintenance: active
---

# docstrfmt — docstrfmt: A formatter for Sphinx flavored reStructuredText.

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

## What it is and what it does

docstrfmt is a command-line tool that automatically formats reStructuredText markup and Python docstrings to a consistent, opinionated style. It draws inspiration from Black and rstfmt, aiming to reduce style discussions and manual formatting work by enforcing a single reasonable format. The tool reads Python files or raw reStructuredText and rewrites docstrings and markup according to its rules, with configurable line length that defaults to Black's 88 characters or can be read from pyproject.toml.

The package depends on Black, libcst, docutils, Sphinx, and related utilities to parse and reformat the text. It runs as a command-line tool or optionally as an HTTP daemon (docstrfmtd) to avoid repeated startup costs. Currently in beta, it covers most common reStructuredText constructs but acknowledges gaps in coverage for less common syntax.

Use it for:

- Enforce consistent docstring formatting across a Python project's codebase automatically.
- Integrate docstring formatting into pre-commit hooks to catch style issues before commit.
- Format standalone reStructuredText files (e.g., documentation, README files) to match project conventions.
- Run as a daemon service to format docstrings on-demand via HTTP in editor plugins or CI pipelines.
- Migrate existing docstrings to a standardized format without manual editing.

## Worth the install?

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

Automatically formats reStructuredText in files and Python docstrings to a consistent style, similar to how Black formats Python code.

Yes, if you work with reStructuredText or Sphinx-style docstrings and want automated, opinionated formatting. The low install friction, active maintenance, permissive license, and zero known vulnerabilities make it a safe choice. The beta status and acknowledged gaps in construct coverage are worth noting if you rely on advanced reStructuredText features, but for typical docstrings and markup it is stable and ready to use.

## Install

pip install docstrfmt
uv add docstrfmt
poetry add docstrfmt

## Installing docstrfmt

Before you install: Low friction: pure Python wheel with no compiled dependencies. Active maintenance, last commit 2026-08-10, and the project is in beta but described as mostly stable.

License in practice: Permissive license (MIT) means you can use, modify, and distribute this package freely in commercial and private projects without significant restrictions.

Quickstart:

pip install docstrfmt

docstrfmt myfile.py
# or read from stdin and write to stdout:
cat myfile.py | docstrfmt

Requires Python 3.10 or later.

Verify before relying:

- Coverage of less common reStructuredText constructs beyond the most common ones mentioned as currently supported.
- Performance characteristics when formatting large files or many files in batch.
- Stability guarantees or breaking-change policy given the beta status.

## Package facts

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

## Tags

restructuredtext formatter, docstring formatter, sphinx documentation formatter, rst code formatter, automatic docstring formatting, python docstring style, reStructuredText linter, code-formatter, docstring-linter, sphinx

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