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.pyor 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.