Skip to main content

pdf2docx-healer

PyPI version Python versions License: MIT CI/CD

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

Problem pdf2docx alone With pdf2docx-healer
Bullet lists (•, -, *) Flattened to plain text, no Word list style Proper List Bullet style with real Word numbering
Numbered lists (1., a., i.) Lost or merged into one paragraph List Number style; lettered/roman via OOXML injection
Nested lists (3+ levels) Indentation lost Level detected from indent, applied to Word
Hyperlinks URL text is plain, not clickable Wrapped in real <w:hyperlink> elements, blue and underlined
CJK fonts (Chinese/Japanese/Korean) Font names like SimSun may not resolve Fallback chain maps to system-available CJK fonts
Scanned PDFs (image-only) "Words count: 0" warning, empty output OCR via Tesseract, then normal conversion
Section headers styled as lists Headers like "4. Numbered List" get list style Detected as headers, kept as Normal paragraphs

Install

pip install pdf2docx-healer

OCR for scanned PDFs runs through PyMuPDF's built-in Tesseract integration, so it needs no extra Python package. Install Tesseract with the language data you need, and make sure tesseract is on PATH or that TESSDATA_PREFIX points to its tessdata folder. Without Tesseract, scanned PDFs are still converted but a warning is logged and no OCR is applied.


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)

heal() returns the output path. It raises FileNotFoundError for a missing input and InvalidInputError (a ValueError) for a non-PDF input, a missing output directory, an output path equal to the input, or an invalid config value. IncompatiblePdf2docxError is raised if the installed pdf2docx does not expose the internals used for list detection; use fix_lists=False to skip that step. Problems in an individual post-processing pass (lists, hyperlinks, fonts) are logged as warnings on the docx_healer logger and the remaining passes still run.

The output file is written only after conversion and post-processing finish, so a failure never leaves a half-written .docx or replaces an existing one. Temporary files created for OCR are always removed, and your input PDF is never modified or deleted.

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. The command exits with status 0 on success, 1 when the conversion fails (missing or invalid input, conversion error), and 2 for invalid 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, trailing punctuation such as the period ending a sentence is left outside the link, and URLs in table cells, nested tables, headers and footers are covered too.
  • 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). Other fonts, for example Calibri, are left as they are.
  • 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.9, < 0.6, PyMuPDF >= 1.23.0, python-docx >= 0.8.11, lxml
  • Tesseract (optional, for OCR; used through PyMuPDF)

Development

pip install -e ".[dev]"
pytest
ruff check src tests
mypy

Metadata

Release files for pdf2docx-healer 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pdf2docx-healer 0.2.0
File Size Uploaded Provenance Actions
pdf2docx_healer-0.2.0.tar.gz 33.1 kB With provenance Details for pdf2docx_healer-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pdf2docx-healer 0.2.0
File Interpreter ABI Platform Actions
pdf2docx_healer-0.2.0-py3-none-any.whl Python 3 none any Details for pdf2docx_healer-0.2.0-py3-none-any.whl

Total release size: 61.1 kB

Release files / pdf2docx_healer-0.2.0.tar.gz

Download URL pdf2docx_healer-0.2.0.tar.gz
Size 33.1 kB
Tags Source
SHA-256 checksum
How to use checksums
b2bd376864bc2cca47815a7e4ab494f82dfee55f9c64dbc732a2e41b749e66ef
BLAKE2b-256 checksum
How to use checksums
201d2cf59c371bc06baabea05931ef4a310b6ded3692f0a2ab252270f2fcc663
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 10, 2026.

Transparency log

Release files / pdf2docx_healer-0.2.0-py3-none-any.whl

Download URL pdf2docx_healer-0.2.0-py3-none-any.whl
Size 28.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
7f33740e03854f853c1817f3c91e28052bd75223a87e85ee1bde800d7e3eb026
BLAKE2b-256 checksum
How to use checksums
c78bfd69c759003bc374259826ca649416c84a39701ebe243f04f34f48330d9c
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 10, 2026.

Transparency log

Security for pdf2docx-healer 0.2.0

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.

Select from 2 files

Attestation for pdf2docx_healer-0.2.0.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 10, 2026.

Transparency log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page