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
| 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'sList Bulletstyle. 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 correctnumFmtsince 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.