Word Footnotes for Python

Create Microsoft Word (.docx) documents with native footnotes using Python and python-docx.

The Problem

The popular python-docx library doesn't support footnotes. This is a long-standing feature request that has never been implemented.

The Solution

This project provides a complete workaround using a template-based approach with XML post-processing. The resulting footnotes:

• Display properly in the document body as superscript numbers
• Appear in the footnote section at the bottom of pages
• Work with Word's built-in footnote navigation
• Are fully editable in Microsoft Word
• Support unlimited footnotes per document

Quick Start

1. Install dependencies

pip install python-docx lxml

2. Create the template (once)

python create_template.py

This creates footnote_template.docx which you'll use as the base for your documents.

3. Create documents with footnotes

fromdocximportDocumentfromfootnote_adderimportFootnoteAdder# Load the templatedoc=Document("footnote_template.docx")
doc._body.clear_content()
# Create footnote adderfootnote_adder=FootnoteAdder()
# Add content with footnotesdoc.add_heading('My Document', 0)
p=doc.add_paragraph()
p.add_run("This statement needs a citation")
footnote_adder.add_footnote(p, "", "Author, Book Title (Publisher, 2024), p. 42.")
p2=doc.add_paragraph()
p2.add_run("Multiple footnotes")
footnote_adder.add_footnote(p2, "", "First source.")
p2.add_run(" in the same paragraph")
footnote_adder.add_footnote(p2, "", "Second source.")
p2.add_run(" work perfectly.")
# Save and finalize (IMPORTANT: call both!)doc.save("my_document.docx")
footnote_adder.finalize_footnotes("my_document.docx")

4. Run the example

python example.py

This creates example_with_footnotes.docx demonstrating various footnote uses.

Files

File	Description
create_template.py	Creates the footnote-enabled template (run once)
footnote_adder.py	The FootnoteAdder class for adding footnotes
example.py	Complete working example
SKILL.md	Claude Code skill documentation

How It Works

1. Template Creation: We create a standard Word document with python-docx, then inject the OOXML infrastructure needed for footnotes (footnotes.xml, endnotes.xml, styles, relationships).

2. Footnote References: When you call add_footnote(), we insert a proper <w:footnoteReference> element in the document XML.

3. Post-Processing: After saving, finalize_footnotes() extracts the .docx (which is a ZIP file), adds the actual footnote content to footnotes.xml, and repacks it.

API Reference

FootnoteAdder

footnote_adder=FootnoteAdder()

add_footnote(paragraph, text, footnote_text)

Add a footnote to a paragraph.

• paragraph: A python-docx paragraph object
• text: Text to add before the footnote marker (can be empty string "")
• footnote_text: The content of the footnote

Returns the footnote run object.

finalize_footnotes(docx_path)

Inject all queued footnotes into the saved document. Must be called after doc.save().

• docx_path: Path to the saved .docx file

Technical Details

This solution required solving several OOXML compatibility issues:

• Namespace declarations: footnotes.xml must declare xmlns:w14 and xmlns:wp14 when using mc:Ignorable="w14 wp14"
• Mac compatibility: Removes Mac-specific namespaces (xmlns:mo, xmlns:mv) that cause errors on Windows
• XML formatting: Ensures double-quote XML declarations (Word rejects single quotes)
• File ordering: OOXML requires specific file order in the ZIP archive

Requirements

• Python 3.6+
• python-docx
• lxml

License

MIT

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

Acknowledgments

This project was developed with assistance from Claude Code to solve the footnote limitation in python-docx.