Docutils: Python Documentation Utilities

0.22.4 verified Tue May 12 auth: no python install: verified quickstart: verified

Docutils is a modular system for processing plaintext documentation into useful formats, such as HTML, LaTeX, and XML. The current version is 0.22.4, released on March 28, 2026. Docutils follows a regular release cadence, with major releases introducing new features and minor releases focusing on bug fixes and improvements.

pip install docutils

Common errors

error ModuleNotFoundError: No module named 'docutils' ↓

cause The `docutils` library is not installed in the Python environment or the Python interpreter cannot find it in the `PATH`.

fix

Install docutils using pip: pip install docutils

error TypeError: 'generator' object is not subscriptable ↓

cause This error often occurs due to an incompatibility between older versions of Sphinx (before 3.0) and `docutils` version 0.18 or later, where Sphinx is using `docutils` for reStructuredText parsing.

fix

Upgrade Sphinx to version 3.0 or later: pip install --upgrade sphinx or pin docutils to an older compatible version, e.g., docutils<0.18.

error ImportError: No module named docutils.core ↓

cause This specific import error usually indicates that `docutils` is either not correctly installed, or there's an issue with the Python environment's ability to locate the installed package.

fix

Ensure docutils is installed for the correct Python interpreter: pip install docutils. If using a virtual environment, activate it before installing. If system-wide tools are pointing to a different Python, adjust the PATH or shebangs.

error ModuleNotFoundError: No module named 'docutils.utils.error_reporting' ↓

cause The `docutils.utils.error_reporting` module was removed or refactored in `docutils` version 0.22, leading to this error when older code attempts to import from it.

fix

Update any code that imports from docutils.utils.error_reporting to use the new error handling mechanisms in docutils 0.22+, or temporarily downgrade docutils to a version prior to 0.22 if an immediate fix is needed for a dependent library.

error ERROR: Could not find a version that satisfies the requirement docutils==X.Y (from versions: none) ERROR: No matching distribution found for docutils==X.Y ↓

cause This error occurs when `pip` cannot find a distribution for the specified version (X.Y) of `docutils` for the current Python version and operating system. This can be due to a typo in the version, the version being too old/new, or network issues preventing access to PyPI.

fix

Check the specified version for correctness. Try installing without a version constraint (pip install docutils) to get the latest compatible version. If a specific older version is required, verify its availability for your Python version and architecture. Also, check network connectivity and proxy settings if applicable.

Warnings

breaking Docutils 0.20 is the last version supporting Python 3.7 and 3.8. ↓

fix Upgrade to Python 3.9 or later to continue receiving support.

deprecated The 'rst2html.py' script is deprecated and will be removed in a future release. ↓

fix Use the 'docutils' command-line tool instead.

gotcha Ensure that the 'docutils' package is installed in your Python environment to avoid ImportError. ↓

fix Install Docutils using 'pip install docutils'.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - 0.07s 22.0M

3.10 slim (glibc) - - 0.06s 23M

3.11 alpine (musl) - - 0.18s 24.6M

3.11 slim (glibc) - - 0.17s 25M

3.12 alpine (musl) - - 0.14s 16.4M

3.12 slim (glibc) - - 0.14s 17M

3.13 alpine (musl) - - 0.14s 16.0M

3.13 slim (glibc) - - 0.13s 17M

3.9 alpine (musl) - - 0.06s 21.5M

3.9 slim (glibc) - - 0.05s 22M

Imports

Publisher
```
from docutils.core import Publisher
```
Ensure correct import path to avoid ImportError.
Reader
```
from docutils.readers.standalone import Reader
```
Ensure correct import path to avoid ImportError.
Writer
```
from docutils.writers.html4css1 import Writer
```
Ensure correct import path to avoid ImportError.

Quickstart verified last tested: 2026-04-23

This script demonstrates how to convert a reStructuredText document to HTML using Docutils. It imports the necessary modules, defines a sample reStructuredText input, and processes it to produce HTML output.

import os
from docutils.core import publish_string
from docutils.readers.standalone import Reader
from docutils.writers.html4css1 import Writer

# Sample reStructuredText input
rst_input = '''
Title
=====

This is a sample reStructuredText document.
'''

# Create Reader and Writer instances
reader = Reader()
writer = Writer()

# Process the input
output = publish_string(source=rst_input.encode('utf-8'), reader=reader, writer=writer)

# Print the HTML output
print(output.decode('utf-8'))