pdf2docx-healer

A drop-in replacement for pdf2docx that actually preserves your formatting.

pdf2docx is a great PDF-to-DOCX converter, but it drops bullet lists, loses hyperlinks, mangles CJK fonts, and chokes on scanned PDFs. pdf2docx-healer wraps pdf2docx and heals all of these issues in a post-processing pass — so your Word documents come out looking the way they should.

Why this exists

Install

pip install pdf2docx-healer

For OCR support on scanned PDFs, also install Tesseract and the optional extra:

pip install "pdf2docx-healer[ocr]"

Quick start

Python API

from docx_healer import heal

# Simplest usage — output goes to "report.docx"
heal("report.pdf", "report.docx")

from docx_healer import heal, HealerConfig

# Full control via config
config = HealerConfig(
    ocr_enabled=True,          # OCR for scanned/image PDFs
    ocr_lang="eng",            # Tesseract language code
    ocr_dpi=300,               # OCR resolution
    ocr_threshold=0.3,         # Fraction of textless pages to trigger OCR
    fix_lists=True,            # Detect & style bullet/numbered lists
    fix_hyperlinks=True,       # Wrap URL text in clickable hyperlinks
    fix_fonts=True,            # Map CJK/unavailable fonts to system fonts
    aggressive_lists=False,    # More aggressive paragraph splitting
    verbose=True,              # Print progress
)

heal("scanned_report.pdf", "output.docx", config=config)

Command line

# Basic conversion
pdf2docx-heal input.pdf -o output.docx

# Scanned PDF with OCR
pdf2docx-heal input.pdf --ocr --ocr-lang eng

# Quiet mode (no progress output)
pdf2docx-heal input.pdf -q

# Skip specific fixes
pdf2docx-heal input.pdf --no-lists --no-hyperlinks

Run pdf2docx-heal --help to see all options.

What it fixes

• Bullet lists — Detects Unicode (•, ◦, ▪, –) and ASCII (-, *, +) bullets, applies Word's List Bullet style. Nested bullets (up to 5 levels) detected from indentation.
• Numbered lists — Detects decimal (1.), parenthesized ((1)), lettered (a.), roman (i.), and outline (1.1) numbering. Lettered/roman use OOXML injection with correct numFmt since Word's built-in styles only support decimal.
• Hyperlinks — Scans runs for http://, https://, www., mailto:, ftp:// and wraps them in <w:hyperlink> elements with external relationship targets. Multiple URLs in one run all get converted.
• CJK font fallback — Maps embedded font names (SimSun, MS-Mincho, HYGoThic-Medium) to system-available equivalents across Windows/macOS/Linux. Character-range detection maps unknown fonts by script (CJK, Arabic, Hebrew, Thai, Devanagari, Cyrillic).
• Scanned PDF OCR — Detects image-only PDFs and runs Tesseract OCR via PyMuPDF. Falls back gracefully if Tesseract isn't installed.
• Smart header detection — Headers like "4. Numbered List" are detected via sequential-reset analysis and kept as Normal paragraphs instead of being styled as list items.

Requirements

• Python 3.8+
• pdf2docx >= 0.5.0, PyMuPDF >= 1.23.0, python-docx >= 0.8.11, lxml
• Tesseract (optional, for OCR)