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

Document Tree / Docutils DTD

  • Allow multiple <term> elements in a <definition_list_item> in Docutils 0.22 (cf. feature-requests:60). Third-party writers may need adaption.

  • Do not lowercase reference names in the refname attribute (matching hyperlinks, footnotes, and citations remains case insensitive), and drop the name attribute from <reference> nodes in Docutils 1.0.

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.

    • Unitless image :width: and :hight: values and dimensions read from the image due to a :scale: option will be written as "width" and "hight" attributes instead of "style" rules to allow specification of the aspect ratio to prevent jank when loading images without overwriting an image size set in a CSS stylesheet in Docutils 0.22 (cf. feature-requests:102). The current behaviour is kept for dimensions with value, so users may specify, e.g. :width: 50px instead of :width: 50 to override CSS stylesheet rules.

    • Change the default value of the initial_header_level setting to None (<h2> if there is a document title, else <h1>) in Docutils 1.0.

    • 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.

  • "manpage" writer:

    • No more changing case in to uppercase, leave it to the source.


  • 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.

    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 (unpublished)

Release 0.21.1 (2024-04-10)

The sdist in 0.21 was incomplete

Release 0.21 (2024-04-09)

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)