Run Black on Python code blocks in documentation files.
Installation
Use pip:
python -m pip install blacken-docsPython 3.9 to 3.14 supported.
Black 22.1.0+ supported.
pre-commit hook
You can also install blacken-docs as a pre-commit hook. Add the following to the repos section of your .pre-commit-config.yaml file (docs):
- repo: https://github.com/adamchainz/blacken-docs
rev: "" # replace with latest tag on GitHub
hooks:
- id: blacken-docs
additional_dependencies:
- black==22.12.0Then, reformat your entire project:
pre-commit run blacken-docs --all-filesSince Black is a moving target, it’s best to pin it in additional_dependencies, and upgrade as appropriate. If you have Black installed as another hook, you can automate upgrading this pinned hook using sync-pre-commit-deps.
Usage
blacken-docs is a command line tool that rewrites documentation files in place. It supports Markdown, reStructuredText, and LaTex files. Additionally, you can run it on Python files to reformat Markdown and reStructuredText within docstrings.
Run blacken-docs with the filenames to rewrite:
blacken-docs README.rstIf any file is modified, blacken-docs exits nonzero.
blacken-docs does not have any ability to recurse through directories. Use the pre-commit integration, globbing, or another technique for applying to many files. For example, with git ls-files | xargs:
git ls-files -z -- '*.md' | xargs -0 blacken-docs…or PowerShell’s ForEach-Object:
git ls-files -- '*.md' | %{blacken-docs $_}blacken-docs currently passes the following options through to Black:
It also has the below extra options:
--check - Don’t modify files but indicate when changes are necessary with a message and non-zero return code.
-E / --skip-errors - Don’t exit non-zero for errors from Black (normally syntax errors).
--rst-literal-blocks - Also format literal blocks in reStructuredText files (more below).
History
blacken-docs was created by Anthony Sottile in 2018. At the end of 2022, Adam Johnson took over maintenance.
Supported code block formats
blacken-docs formats code blocks matching the following patterns.
Markdown
In “python” blocks:
```python
def hello():
print("hello world")
```And “pycon” blocks:
```pycon
>>> def hello():
... print("hello world")
...
```Prevent formatting within a block using blacken-docs:off and blacken-docs:on comments:
<!-- blacken-docs:off -->
```python
# whatever you want
```
<!-- blacken-docs:on -->Within Python files, docstrings that contain Markdown code blocks may be reformatted:
def f():
"""docstring here
```python
print("hello world")
```
"""reStructuredText
In “python” blocks:
.. code-block:: python
def hello():
print("hello world")In “pycon” blocks:
.. code-block:: pycon
>>> def hello():
... print("hello world")
...Prevent formatting within a block using blacken-docs:off and blacken-docs:on comments:
.. blacken-docs:off
.. code-block:: python
# whatever you want
.. blacken-docs:onUse --rst-literal-blocks to also format literal blocks:
An example::
def hello():
print("hello world")Literal blocks are marked with :: and can be any monospaced text by default. However Sphinx interprets them as Python code by default. If your project uses Sphinx and such a configuration, add --rst-literal-blocks to also format such blocks.
Within Python files, docstrings that contain reStructuredText code blocks may be reformatted:
def f():
"""docstring here
.. code-block:: python
print("hello world")
"""LaTeX
In minted “python” blocks:
\begin{minted}{python}
def hello():
print("hello world")
\end{minted}In minted “pycon” blocks:
\begin{minted}{pycon}
>>> def hello():
... print("hello world")
...
\end{minted}In PythonTeX blocks:
\begin{pycode}
def hello():
print("hello world")
\end{pycode}Prevent formatting within a block using blacken-docs:off and blacken-docs:on comments:
% blacken-docs:off
\begin{minted}{python}
# whatever you want
\end{minted}
% blacken-docs:on1 maintainer
Metadata
1 maintainer
Release files for blacken-docs 1.20.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| blacken_docs-1.20.0.tar.gz | 15.0 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| blacken_docs-1.20.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 23.3 kB
Release files / blacken_docs-1.20.0.tar.gz
| Download URL | blacken_docs-1.20.0.tar.gz |
|---|---|
| Size | 15.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
2d5b6caf6e7da5694b1eba97f9132c1ab9f14f221c82205ec473a6e74fbb2c6d
|
|
BLAKE2b-256 checksum How to use checksums |
20bcc8fbeb90232c3afe0b369de4014c50925a5b3e6fcba5a784d96377da3d09
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 8, 2025.
Transparency logRelease files / blacken_docs-1.20.0-py3-none-any.whl
| Download URL | blacken_docs-1.20.0-py3-none-any.whl |
|---|---|
| Size | 8.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a0d842811ee07802dec920d3cf831e21f6eb017712748b488489aa3688770f1e
|
|
BLAKE2b-256 checksum How to use checksums |
5ce763af39c07bbb019feb1e4f89638410ec08101b59f094c51eb6bd5667b9e9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 8, 2025.
Transparency log
