Install & Compatibility
Where this runs
tested against v0.23 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.108s · 22.1MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.0s · import 0.104s · 23MB
20MB installed
● package 20MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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.
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'))
rst2html --version
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'docutils'
The `docutils` library is not installed in the Python environment or the Python interpreter cannot find it in the `PATH`.
fixInstall docutils using pip: `pip install docutils`
TypeError: 'generator' object is not subscriptable
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.
fixUpgrade Sphinx to version 3.0 or later: `pip install --upgrade sphinx` or pin `docutils` to an older compatible version, e.g., `docutils<0.18`.
ImportError: No module named docutils.core
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.
fixEnsure `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.
ModuleNotFoundError: No module named 'docutils.utils.error_reporting'
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.
fixUpdate 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: Could not find a version that satisfies the requirement docutils==X.Y (from versions: none) ERROR: No matching distribution found for docutils==X.Y
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.
fixCheck 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.
Upgrade
Version history
0.23latest on PyPI · released May 27, 2026
Audit
Dependencies
No dependency data recorded yet.