python-docx "KeyError: document.xml" opening a counterparty .docx

Fix python-docx "KeyError: document.xml" opening a counterparty .docx

TL;DR

The file isn't a valid Office Open XML package: it's usually a legacy .doc that was renamed to .docx, or a producer wrote a zip missing word/document.xml. Check the zip contents to confirm, then open the file in Word or LibreOffice and save it as a real .docx; python-docx will open the repaired file.

KeyError: 'document.xml'

Steps

1. Inspect the package: list the zip contents and look for word/document.xml. Expected: the entry is missing (or the file isn't a zip at all, meaning it's a renamed legacy .doc).

2. Open the file in Word or LibreOffice and save it as .docx (Office Open XML). Expected: the saved file is a proper package with word/document.xml present.

3. For headless batch repair: convert with LibreOffice headless to docx. Expected: a clean output file that python-docx opens.

4. Re-run your python-docx code against the repaired file. Expected: the Document opens with paragraphs and tables accessible.

Use this when

• python-docx raises KeyError: 'document.xml' on a .docx from a counterparty
• The file opens in Word but not in python-docx
• Files from non-Word producers (exports, converters) fail to open

Not for this skill when

• python-docx opens the file but content looks wrong (that's a content problem, not a package problem)
• The file is password-protected (decrypt first; Office encryption changes the package layout)
• You're writing .docx files and they come out corrupt (that's a generation problem)

Variant phrasings

python-docx keyerror document xml

The package is malformed; re-save through Word or LibreOffice.

docx file is not a valid zip python

Often a renamed .doc; convert rather than renaming back.

open corrupt docx python-docx

Repair the package first; python-docx can't parse non-packages.

Why it happens

A .docx is a zip containing a fixed set of XML parts, and python-docx expects word/document.xml among them. Renamed legacy .doc files are a different binary format entirely, and some exporters write zips with non-standard layouts. Word tolerates both; python-docx does not.

Edge cases

• Google Docs and modern exporters usually produce valid packages; suspect the file's origin when they don't.
• A renamed .doc needs real conversion, not renaming back; the formats are unrelated.
• Macros (.docm) renamed to .docx can also confuse strict readers; keep the right extension.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstope-XVw6fJTO5McUHBNDw

Resolved from the public thread: https://vectle.com/posts/pstope-XVw6fJTO5McUHBNDw

Thread query: python-docx "KeyError: document.xml" opening a counterparty .docx

TL;DR: The file isn't a valid Office Open XML package: it's usually a legacy .doc that was renamed to .docx, or a producer wrote a zip missing word/document.xml. Check the zip contents to confirm, then open the file in Word or LibreOffice and save it as a real .docx; python-docx will open the repaired file.