Docutils | Overview | About | Users | Reference | Developers

Docutils Release Notes


Web site:

This document summarizes the major changes in previous and upcoming releases. For a more detailed list of changes, please see the Docutils HISTORY.

Future changes

Command line interface

  • The command-line usage pattern will change:

    • Remove short options -i and -o in Docutils 0.22. Use the long equivalents --input-encoding and --output-encoding.

    • Stop accepting the DESTINATION positional argument in Docutils 1.0. Use output redirection or the option --output=DESTINATION (available since Docutils 0.20).

    • Accept more than one source document and the short option -o for --output in Docutils 2.0

    For the rationale, see

Input encoding

  • Change the default input encoding from None (auto-detect) to "utf-8" in Docutils 0.22.

  • Remove the input encoding auto-detection code in Docutils 1.0 or later.


  • The default HTML writer will change in Docutils 2.0:

    The rst2html front end and get_writer_by_name('html') select "html4css1" now and will select "html5" in Docutils 2.0 and later.

    • Use rst2html4, docutils --writer=html4, or get_writer_by_name('html4') if you depend on stability of the generated HTML code, e.g. because you use a custom style sheet or post-processing that may break otherwise.

    • Use rst2html5, docutils or get_writer_by_name('html5') if you want a HTML5 document.

  • "html5" writer:

    • Move attribution behind the blockquote to comply with the "living standard". (HTML5 allows <cite> elements inside a blockquote.)

    • Change the default value for math_output to "MathML" in Docutils 0.22.

    • Remove option --embed-images (obsoleted by "image_loading") in Docutils 2.0.

  • "latex2e" writer:

    • Change default of use_latex_citations setting to True in Docutils 1.0.

    • Change default of legacy_column_widths setting to False in Docutils 1.0.

    • Remove use_verbatim_when_possible setting (use literal_block_env: verbatim) in Docutils 2.0.

    • Don't wrap references with custom reference-label in a \hyperref command in Docutils 0.22. Specify, e.g., "ref" instead of "ref*" to keep generating hyperlinks.

  • "null" writer: output will change to the empty string in Docutils 0.22.


  • Remove parsers.rst.directives.CSVTable.HeaderDialect in Docutils 0.22.

  • Remove the "rawsource" argument from nodes.Text.__init__() in Docutils 2.0.

  • Drop support for old-format configuration files in Docutils 2.0.

  • Remove the --html-writer option of the application (obsoleted by the "writer" setting since Docutils 0.18) in Docutils 2.0.

  • Revise the String I/O interface used by the publish_string() and publish_from_doctree() publisher convenience functions. (In Python 3, name and behaviour no longer match.)

  • Move math format conversion from docutils/utils/math (called from docutils/writers/ to a transform.

  • Remove mistranslated localizations of the "admonition" directive name in Docutils 0.22 or later.

    Use the English term, matching translations introduced in Docutils 0.21, or specific admonitions instead of "aanmaning" (nl), "admonition" (fr), "ammonizione" (it), "ermahnung" (de), "exhortación" (es), "formaning" (da), "sciigo" (eo), "upomnienie" (pl), "vermaning" (af), to avoid errors in future conversions.

Release 0.21 (unpublished)

Release 0.20.1 (2023-05-17)

Bugfix release. See HISTORY for details.

Release 0.20 (2023-05-04)

Release 0.19 (2022-07-05)

(Release 0.19b1 (2022-06-21))

Release 0.18.1 (2021-12-23)

Release 0.18 (2021-10-26)

Release 0.17.1 (2021-04-16)

Release 0.17 (2021-04-03)

Release 0.16 (2020-01-12)

Docutils 0.16.x supports Python 2.7 and Python >= 3.5 natively, without the use of the 2to3 tool.

Release 0.15 (2019-07-20)

Docutils 0.15.x is compatible with Python versions 2.6, 2.7 and 3.3 to 3.5.

Release 0.14 (2017-08-03)

Release 0.13.1 (2016-12-09)

Release 0.12 (2014-07-06)

Small changes only, release current state

Release 0.11 (2013-07-22)

Release 0.10 (2012-12-16)

Docutils 0.10 is compatible with Python versions from 2.4 to 3.2.

Release 0.9.1 (2012-06-17)

Release 0.9 (2012-05-02)

Release 0.8.1 (2011-08-30)

Release 0.8 (2011-07-07)



Release 0.7 (2010-07-07)



Release 0.6 (2009-10-11)

Docutils 0.6 is compatible with Python versions from 2.3 up to 2.6 and convertible to 3.1 code.

Release 0.5 (2008-06-25)






Release 0.4 (2006-01-09)






Release 0.3.9 (2005-05-26)

Release 0.3.7 (2004-12-24)

Release 0.3.5 (2004-07-29)