Skip to main content

sphinx2word

A Sphinx builder that writes your documentation as a Microsoft Word (.docx) document. It writes the document using Office Open XML and works on Linux, Mac and Windows, including CI systems such as GitHub Actions and GitLab CI. It does not need a physical instance of Word: the result is always a single, complete .docx file, with its images and styles inside it.

Only Word can lay out the pages, so a document built without Word has its table of contents and lists of figures and tables filled in, but without page numbers. When it is first opened, Word asks whether to update the fields in the document; answer Yes to add the page numbers. Windows users with Word installed can avoid this extra step by installing pywin32 into their Python environment; the builder then lets Word fill in the page numbers during the build. See Building without Word.

The result is a normal Word document that people can edit, comment on, restyle with their own template and merge into larger reports:

  • Equations: LaTeX math becomes native, editable Word equations.
  • Headings: headings use Word's heading styles, and Word numbers them.
  • Bibliographies using Sphinx bibtex are supported.
  • Captions and cross-references: captions and references are Word fields. Insert Caption, Cross-reference and Table of Figures all work, and the numbers follow the document when it is merged into another one.

Our group also works on various engineering contracts and we like to apply standard, front-style, content at the beginning of the document. To help us support this we include options in the builder for,

  • Front matter: a table of contents, a list of figures and a list of tables follow the title page.
  • Contract reports: an optional cover page with contributor and distribution lists, and a change record taken from conf.py or from git tags.

We have configured the builder so it can use Word's internal scheme for labelling sections, figures, tables etc. This is in contrast to the other option where we simply use the section/figure/table/equations numbers as generated by Sphinx. This feature is important if you are merging multiple documents into one larger document and need to update all figures, tables, equations, sections in one unified update. The variable word_update_fields in conf.py controls this feature. See Numbering, captions and cross-references.

Installation

pip install sphinx2word

The only mandatory dependency is Sphinx 5 or later (Python 3.8+). Some optional packages are used if they are installed:

Package Use
Pillow Read the size and resolution of JPEG, GIF, BMP and TIFF images (PNG and SVG are read without it)
cairosvg Make PNG fallbacks of SVG images for Word versions older than 2016
pywin32 (Windows) With Word installed, let Word fill in the table of contents and page numbers after the build, so the file opens without a prompt. Without it the document is still written, and Word asks to update the fields the first time it is opened

You can install the optional packages yourself or the installation will install the optional packages for you if you supply the extra images (Pillow, cairosvg) and word (pywin32) options to the installation:

pip install "sphinx2word[images,word]"

Quick start

Add the extension to conf.py:

extensions = [
    "sphinx.ext.autodoc",
    "sphinx.ext.mathjax",
    # ...
    "sphinx2word",
]

and build with the word builder:

python -m sphinx -b word docs/source docs/_build/word

The output goes in the folder given on the command line, here docs/_build/word. The file is named <project>-<version>.docx using the project and version variables in conf.py. Alternatively the filename can be set using variable word_filename in conf.py (see Configuration). The whole toctree of the Sphinx document becomes one Word document.

It can be helpful to modify your conf.py so the extension is only used if it is installed in your python environment,

import importlib.util
if importlib.util.find_spec("sphinx2word") is not None:
    extensions.append("sphinx2word")

This is the technique we use in our CI/CD chain when we only wish to build HTML and do not want to install the sphinx2word package.

What you get

Sphinx / reStructuredText Word
Master document title Title page, or the cover page of a contract report
— Table of contents, list of figures, list of tables
Sections Heading 1 … Heading 9; numbered by Word if the toctree is :numbered:
:math:, .. math:: Native Word equations; numbered equations have their number on the right
Figures and images (PNG, JPEG, GIF, BMP, TIFF, SVG) Inline pictures with captions
Tables (grid, simple, list-table, csv-table) Word tables with header rows, spanned cells, and lists and math in cells
Captions Figure {SEQ Figure}: …, as Word's Insert Caption writes them
:numref:, :eq:, :ref:, :doc: Word cross-references (REF fields); other links are hyperlinks
Footnotes Word footnotes
Citations (sphinxcontrib-bibtex or reST) Bibliography entries with aligned labels; citations link to them
code-block, literal blocks Shaded code blocks, coloured with Pygments, with line numbers and highlighted lines
.. index::, :index:, API entries Word index entries (XE fields) and an index at the end
Python modules A Python module index before the index
word_appendices Appendices after the chapters, numbered "Appendix A:", A.1, A.1.1
language Contents, lists, indexes and caption labels in the project's language
graphviz, inheritance-diagram Diagrams drawn by Graphviz, inserted as pictures
.. raw:: latex \newpage, class landscape, .. raw:: openxml Page breaks, landscape pages, and raw WordprocessingML
Lists (bullet, enumerated, definition, field, option) Word lists; each enumerated list restarts at its own start number
note, warning, tip, todo, … Shaded boxes with a coloured bar
autodoc, napoleon, numpydoc, Breathe API entries Signature lines and indented descriptions

Nodes that sphinx2word does not know are not dropped: their text is written as normal paragraphs, and the build log lists their types. .. only:: word includes content in the Word output only.

Documentation

Page Contents
Configuration Every word_* setting in conf.py
What is converted How each Sphinx and reST construct appears in Word, and the limits
Math The LaTeX supported in equations, macros, and what happens to errors
Numbering, captions and cross-references Word fields, caption numbering, merging into larger documents, the "update fields" prompt
Contract reports Cover page, contributor and distribution lists, change record from git
Word templates and styles Using your own template, and the list of styles sphinx2word uses
Example document A complete Sphinx project that shows every feature, with its reST
Development Tests, code layout, checking the output in Word, CI and releases
Changelog What changed in each version

Licence

MIT, © 2023-2026 Nick Lloyd. See LICENSE. You may use, copy, change and distribute sphinx2word, including in commercial work, as long as you keep the copyright and licence notice.

Origins

sphinx2word started as a fork of docxsphinx by Mher Kazandjian and Hugo Buddelmeijer, itself based on sphinxcontrib-WordAppBuilder by Takayuki Shimizukawa. Both are MIT-licensed. Version 1.0 is a rewrite that writes the .docx file itself, but the project is grateful for where it began.

Metadata

Release files for sphinx2word 1.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for sphinx2word 1.1.1
File Size Uploaded Provenance Actions
sphinx2word-1.1.1.tar.gz 1.1 MB With provenance Details for sphinx2word-1.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for sphinx2word 1.1.1
File Interpreter ABI Platform Actions
sphinx2word-1.1.1-py3-none-any.whl Python 3 none any Details for sphinx2word-1.1.1-py3-none-any.whl

Total release size: 1.2 MB

Release files / sphinx2word-1.1.1.tar.gz

Download URL sphinx2word-1.1.1.tar.gz
Size 1.1 MB
Tags Source
SHA-256 checksum
How to use checksums
70780cc1f085865a174c11529d764d3632ae6beedc69e686757c353f8b3827bf
BLAKE2b-256 checksum
How to use checksums
15945d0f6fd9ab4434b5058680b6f90bbc7f5c613da88628be17f1480de64731
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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 Nov 12, 2026.

Transparency log

Release files / sphinx2word-1.1.1-py3-none-any.whl

Download URL sphinx2word-1.1.1-py3-none-any.whl
Size 68.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
1ce74d0231185d23b81380a79bc7eb6694f66559a99be5f0f926af5a064bf97d
BLAKE2b-256 checksum
How to use checksums
f4c435fae3710636b4c5e5e356715cd1eb15f2e2802127424230ba0e2c39333a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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 Nov 12, 2026.

Transparency log

Security for sphinx2word 1.1.1

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.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for sphinx2word-1.1.1.tar.gz

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 Nov 12, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.1.1 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page