Skip to content

Python tool for converting files and office documents to Markdown.

fix: handle DOCX files with inconsistent ZIP filename casing (#1812) (#2016)

liyrdsa5ddc8efd557
diff --git a/packages/markitdown-ocr/src/markitdown_ocr/_docx_converter_with_ocr.py b/packages/markitdown-ocr/src/markitdown_ocr/_docx_converter_with_ocr.py
index 9fd3b07e..f0201689 100644
--- a/packages/markitdown-ocr/src/markitdown_ocr/_docx_converter_with_ocr.py
+++ b/packages/markitdown-ocr/src/markitdown_ocr/_docx_converter_with_ocr.py
@@ -94,9 +94,16 @@ class DocxConverterWithOCR(HtmlConverter):
kwargs.get("ocr_service") or self.ocr_service
)
+ # Pre-process once, up front, so that every subsequent read sees the
+ # repaired archive. pre_process_docx() also fixes .docx files whose ZIP
+ # local file headers disagree with the central directory; reading the
+ # original stream first would make those raise, or silently yield no
+ # images and drop the OCR output.
+ pre_process_stream = pre_process_docx(file_stream)
+
# Read the embedded style map and combine with any provided style map
caller_style_map = kwargs.get("style_map")
- embedded_style_map = _read_embedded_style_map(file_stream)
+ embedded_style_map = _read_embedded_style_map(pre_process_stream)
style_map = "\n".join(
part
@@ -110,12 +117,13 @@ class DocxConverterWithOCR(HtmlConverter):
if ocr_service:
# 1. Extract and OCR images — returns raw text per image
- file_stream.seek(0)
- image_ocr_map = self._extract_and_ocr_images(file_stream, ocr_service)
+ pre_process_stream.seek(0)
+ image_ocr_map = self._extract_and_ocr_images(
+ pre_process_stream, ocr_service
+ )
# 2. Convert DOCX → HTML via mammoth
- file_stream.seek(0)
- pre_process_stream = pre_process_docx(file_stream)
+ pre_process_stream.seek(0)
html_result = mammoth.convert_to_html(
pre_process_stream,
style_map=style_map,
@@ -144,7 +152,7 @@ class DocxConverterWithOCR(HtmlConverter):
return DocumentConverterResult(markdown=md)
else:
# Standard conversion without OCR
- pre_process_stream = pre_process_docx(file_stream)
+ pre_process_stream.seek(0)
return self._html_converter.convert_string(
mammoth.convert_to_html(
pre_process_stream,
diff --git a/packages/markitdown-ocr/tests/test_docx_converter.py b/packages/markitdown-ocr/tests/test_docx_converter.py
index fcd0944b..2538206d 100644
--- a/packages/markitdown-ocr/tests/test_docx_converter.py
+++ b/packages/markitdown-ocr/tests/test_docx_converter.py
@@ -10,6 +10,8 @@ OCR block format used by the converter:
[End OCR]*
"""
+import io
+import struct
import sys
import zipfile
from pathlib import Path
@@ -279,3 +281,59 @@ def test_docx_underlined_text_is_preserved_with_ocr(
f, StreamInfo(extension=".docx"), ocr_service=svc
).markdown
assert "plain <u>underlined</u>" in md
+
+
+# ---------------------------------------------------------------------------
+# ZIP local file header casing mismatch
+# ---------------------------------------------------------------------------
+
+
+def _uppercase_local_header_names(docx_bytes: bytes) -> bytes:
+ """Uppercase every local file header filename, leaving the central directory
+ untouched, to mimic generators that disagree with themselves about casing."""
+ raw = bytearray(docx_bytes)
+ offset = patched = 0
+ while offset + 30 <= len(raw) and raw[offset : offset + 4] == b"PK\x03\x04":
+ fname_len = struct.unpack_from("<H", raw, offset + 26)[0]
+ extra_len = struct.unpack_from("<H", raw, offset + 28)[0]
+ comp_size = struct.unpack_from("<I", raw, offset + 18)[0]
+ name = raw[offset + 30 : offset + 30 + fname_len]
+ if name.upper() != name:
+ raw[offset + 30 : offset + 30 + fname_len] = name.upper()
+ patched += 1
+ offset += 30 + fname_len + extra_len + comp_size
+ assert patched, "fixture produced no mismatched local file headers"
+ return bytes(raw)
+
+
+def test_docx_zip_filename_casing_mismatch_preserves_ocr(svc: MockOCRService) -> None:
+ """OCR output survives a .docx whose local file headers disagree with the
+ central directory on casing.
+
+ The image extraction swallows every exception, so an unrepaired stream used
+ to yield an empty OCR map and silently drop the OCR blocks rather than fail.
+ """
+ path = TEST_DATA_DIR / "docx_image_middle.docx"
+ if not path.exists():
+ pytest.skip(f"Test file not found: {path}")
+
+ original = path.read_bytes()
+ mismatched = _uppercase_local_header_names(original)
+
+ # Plain zipfile cannot read the mismatched archive ...
+ with pytest.raises(zipfile.BadZipFile):
+ with zipfile.ZipFile(io.BytesIO(mismatched), "r") as zf:
+ for name in zf.namelist():
+ zf.read(name)
+
+ # ... but the converter produces the same output it does for the original.
+ converter = DocxConverterWithOCR()
+ expected = converter.convert(
+ io.BytesIO(original), StreamInfo(extension=".docx"), ocr_service=svc
+ ).markdown
+ actual = converter.convert(
+ io.BytesIO(mismatched), StreamInfo(extension=".docx"), ocr_service=svc
+ ).markdown
+
+ assert _MOCK_TEXT in actual
+ assert actual == expected
diff --git a/packages/markitdown/src/markitdown/converter_utils/docx/pre_process.py b/packages/markitdown/src/markitdown/converter_utils/docx/pre_process.py
index ee5da4e6..e569c0f2 100644
--- a/packages/markitdown/src/markitdown/converter_utils/docx/pre_process.py
+++ b/packages/markitdown/src/markitdown/converter_utils/docx/pre_process.py
@@ -1,3 +1,4 @@
+import struct
import zipfile
from io import BytesIO
from typing import BinaryIO
@@ -138,6 +139,66 @@ def _pre_process_math(content: bytes) -> bytes:
return str(soup).encode()
+def _fix_zip_filename_casing(input_docx: BinaryIO) -> BinaryIO:
+ """
+ Fix ZIP files where local file header filenames differ in casing
+ from the central directory filenames.
+
+ Some document generators (e.g. certain Microsoft Word versions,
+ legal document systems) produce .docx/.pptx files where the central
+ directory records one casing (e.g. 'customXml/item2.xml') but
+ the local file headers record another (e.g. 'customXML/item2.xml').
+ Python's zipfile module raises BadZipFile when reading such files.
+
+ This function patches local file header filenames to match the
+ central directory, which is the authoritative source used by
+ zipfile.ZipFile.
+ """
+ input_docx.seek(0)
+ raw = bytearray(input_docx.read())
+
+ # Read the central directory to get authoritative filenames
+ try:
+ with zipfile.ZipFile(BytesIO(raw), "r") as zf:
+ cd_entries = {
+ zi.header_offset: (zi.orig_filename, zi.flag_bits)
+ for zi in zf.infolist()
+ }
+ except zipfile.BadZipFile:
+ # Can't even read central directory — return as-is, let it fail later
+ input_docx.seek(0)
+ return input_docx
+
+ patched = False
+ for offset, (cd_name, flag_bits) in cd_entries.items():
+ # Verify local file header signature
+ if offset + 30 > len(raw) or raw[offset : offset + 4] != b"PK\x03\x04":
+ continue
+
+ local_fname_len = struct.unpack_from("<H", raw, offset + 26)[0]
+ if offset + 30 + local_fname_len > len(raw):
+ continue
+
+ local_name = bytes(raw[offset + 30 : offset + 30 + local_fname_len])
+ # ZIP filenames are cp437 unless flag bit 11 marks them as UTF-8, which is
+ # how zipfile decoded orig_filename in the first place.
+ central_name = cd_name.encode("utf-8" if flag_bits & 0x800 else "cp437")
+
+ # Only patch if lengths match but content differs (casing mismatch)
+ if (
+ local_name != central_name
+ and len(local_name) == len(central_name)
+ and local_name.lower() == central_name.lower()
+ ):
+ raw[offset + 30 : offset + 30 + local_fname_len] = central_name
+ patched = True
+
+ if patched:
+ return BytesIO(bytes(raw))
+ input_docx.seek(0)
+ return input_docx
+
+
def _pre_process_styles(content: bytes) -> bytes:
"""
Repairs DOCX style definitions that Mammoth cannot read.
@@ -175,6 +236,9 @@ def pre_process_docx(input_docx: BinaryIO) -> BinaryIO:
Returns:
BinaryIO: A binary output stream representing the processed DOCX file.
"""
+ # Fix ZIP filename casing mismatch before any processing
+ input_docx = _fix_zip_filename_casing(input_docx)
+
output_docx = BytesIO()
# The pre-processing steps to apply to each file in the .docx
pre_process_enable_files = {
diff --git a/packages/markitdown/tests/test_module_misc.py b/packages/markitdown/tests/test_module_misc.py
index 22df3aad..2fa52f71 100644
--- a/packages/markitdown/tests/test_module_misc.py
+++ b/packages/markitdown/tests/test_module_misc.py
@@ -479,6 +479,134 @@ def test_docx_equations() -> None:
assert block_equations, "No block equations found in the document."
+def test_docx_zip_filename_casing_mismatch() -> None:
+ """Test that DOCX files with inconsistent ZIP filename casing are handled.
+
+ Some document generators produce .docx files where the central directory
+ records one casing (e.g. 'word/document.xml') but the local file headers
+ record another (e.g. 'Word/Document.XML'). Python's zipfile module raises
+ BadZipFile when reading such files. This test verifies that MarkItDown
+ handles this gracefully.
+
+ See: https://github.com/microsoft/markitdown/issues/1812
+ """
+ import struct
+
+ markitdown = MarkItDown()
+ docx_file = os.path.join(TEST_FILES_DIR, "test.docx")
+
+ # Read the original docx and get its expected content
+ original_result = markitdown.convert(docx_file)
+ assert original_result.markdown.strip(), "Original DOCX should have content"
+
+ # Read raw bytes and corrupt the local file header filenames
+ with open(docx_file, "rb") as f:
+ raw = bytearray(f.read())
+
+ # Find all local file headers and uppercase their filenames
+ corrupted = bytearray(raw)
+ offset = 0
+ patched_count = 0
+ while offset + 30 <= len(corrupted):
+ if corrupted[offset : offset + 4] != b"PK\x03\x04":
+ break
+ fname_len = struct.unpack_from("<H", corrupted, offset + 26)[0]
+ extra_len = struct.unpack_from("<H", corrupted, offset + 28)[0]
+ if offset + 30 + fname_len > len(corrupted):
+ break
+ # Uppercase the filename in the local header
+ old_name = corrupted[offset + 30 : offset + 30 + fname_len]
+ new_name = old_name.upper()
+ if old_name != new_name:
+ corrupted[offset + 30 : offset + 30 + fname_len] = new_name
+ patched_count += 1
+ comp_size = struct.unpack_from("<I", corrupted, offset + 18)[0]
+ offset = offset + 30 + fname_len + extra_len + comp_size
+
+ assert patched_count > 0, "Should have patched at least one local file header"
+
+ # Verify the corrupted file would fail with plain zipfile
+ with pytest.raises(zipfile.BadZipFile):
+ with zipfile.ZipFile(io.BytesIO(bytes(corrupted)), "r") as zf:
+ for name in zf.namelist():
+ zf.read(name)
+
+ # Verify MarkItDown can still convert it
+ corrupted_result = markitdown.convert_stream(
+ io.BytesIO(bytes(corrupted)),
+ file_extension=".docx",
+ )
+ assert (
+ corrupted_result.markdown.strip()
+ ), "Corrupted DOCX should still produce content"
+ # Content should be equivalent to the original
+ assert (
+ original_result.markdown.strip() == corrupted_result.markdown.strip()
+ ), "Corrupted DOCX should produce the same output as original"
+
+
+def test_docx_zip_filename_non_casing_mismatch_still_rejected() -> None:
+ """Only case-only local/central filename disagreements are repaired.
+
+ Equal encoded length does not imply two names differ only in case, so the
+ repair must not be used to wave through archives whose local and central
+ directory names genuinely disagree -- zipfile rejects those for good
+ reason, and honouring that keeps the workaround scoped to issue #1812.
+ """
+ import struct
+
+ from markitdown.converter_utils.docx.pre_process import (
+ _fix_zip_filename_casing,
+ )
+
+ def build_zip(first_name: str) -> bytes:
+ buf = io.BytesIO()
+ with zipfile.ZipFile(buf, "w") as zf:
+ zf.writestr(first_name, b"payload-a")
+ zf.writestr("word/document.xml", b"payload-b")
+ return buf.getvalue()
+
+ def replace_first_local_name(data: bytes, new_name: bytes) -> bytes:
+ """Rewrite only the first local file header's name, leaving the central
+ directory -- the authoritative copy -- untouched."""
+ raw = bytearray(data)
+ fname_len = struct.unpack_from("<H", raw, 26)[0]
+ assert len(new_name) == fname_len, "mutation must preserve the length"
+ raw[30 : 30 + fname_len] = new_name
+ return bytes(raw)
+
+ def reads_cleanly(data: bytes) -> bool:
+ try:
+ with zipfile.ZipFile(io.BytesIO(data), "r") as zf:
+ for name in zf.namelist():
+ zf.read(name)
+ except zipfile.BadZipFile:
+ return False
+ return True
+
+ original = "[Content_Types].xml"
+
+ # A case-only mismatch is repaired ...
+ case_only = replace_first_local_name(build_zip(original), original.upper().encode())
+ assert not reads_cleanly(case_only)
+ repaired = _fix_zip_filename_casing(io.BytesIO(case_only))
+ assert reads_cleanly(repaired.read())
+
+ # ... but an equal-length mismatch that is not case-only is left alone,
+ # so zipfile still refuses the archive.
+ for mutated_name in (
+ b"ZBnoudou^Uxqdr\\/ylm", # unrelated, same length
+ b"[Content_Types].xmy", # a single differing character
+ b"[content_types]/xml", # differs only outside the cased characters
+ ):
+ data = replace_first_local_name(build_zip(original), mutated_name)
+ assert not reads_cleanly(data), f"{mutated_name!r} should not be readable"
+ result = _fix_zip_filename_casing(io.BytesIO(data))
+ assert not reads_cleanly(
+ result.read()
+ ), f"{mutated_name!r} must not be silently repaired"
+
+
def test_docx_malformed_equations() -> None:
"""Malformed equations should not crash the converter (issue #1979)."""
import zipfile
@@ -1478,6 +1606,8 @@ if __name__ == "__main__":
test_data_uris,
test_file_uris,
test_docx_comments,
+ test_docx_zip_filename_casing_mismatch,
+ test_docx_zip_filename_non_casing_mismatch_still_rejected,
test_input_as_strings,
test_markitdown_remote,
test_speech_transcription,