Registry / serialization / html-for-docx

html-for-docx

JSON →
library1.1.5pypypi✓ verified 84d ago

html-for-docx is a Python library designed to convert HTML content into Microsoft Word (.docx) documents easily and efficiently. It is an actively maintained fork of the discontinued `pqzx/html2docx` project, providing a more reliable solution for generating Word documents from various HTML inputs. The current version is 1.1.4, with a consistent release cadence focusing on bug fixes and feature enhancements, including improved CSS and HTML tag support.

pip install html-for-docx
INSTALL
IMPORT
SIG · HTML-FOR-DOCX
H
html-for-docx
serializationpythonv1.1.5
Install
2.4s avg
Import
688ms
Disk
33MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.1.5 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.920 runs
installs and imports cleanly · install 0.0s · import 0.705s · 34.2MB
glibc
py 3.103.920 runs
installs and imports cleanly · install 2.4s · import 0.670s · 35MB
33MB installed
● package 33MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

HtmlToDocx
from html4docx import HtmlToDocx

This quickstart demonstrates the core functionalities of html-for-docx: adding HTML strings to a `python-docx` Document object, saving to a file, converting to an in-memory BytesIO object, and converting directly from an HTML file.

from docx import Document from html4docx import HtmlToDocx from io import BytesIO # Example 1: Add HTML to an existing Document object and save document = Document() # Or load an existing .docx: Document('template.docx') parser = HtmlToDocx() html_string = '<h1>Hello world</h1><p>This is a <strong>paragraph</strong> with some <em>formatting</em>.</p>' parser.add_html_to_document(html_string, document) document.save('output.docx') print("Saved 'output.docx' with basic HTML content.") # Example 2: Convert an HTML string directly to a BytesIO object (in-memory) buffer = BytesIO() parser_in_memory = HtmlToDocx() html_string_2 = '<p style="color: blue;">This text is blue.</p>' parser_in_memory.add_html_to_document(html_string_2, buffer) # To read from the buffer again, reset its position buffer.seek(0) print(f"Generated DOCX in memory, size: {len(buffer.getvalue())} bytes.") # Example 3: Convert an HTML file directly # Create a dummy HTML file for demonstration with open('input.html', 'w', encoding='utf-8') as f: f.write('<h2>Content from file</h2><p>This was converted from an HTML file.</p>') file_parser = HtmlToDocx() file_parser.parse_html_file('input.html', 'output_from_file.docx') print("Saved 'output_from_file.docx' from 'input.html'.")
Debug
Known issues
gotchaHTML to DOCX conversion inherently carries limitations, especially with complex CSS layouts, responsive designs, or intricate styling. The output DOCX might not perfectly match the browser's rendering of the HTML.
fix
Simplify HTML/CSS where possible. Test complex layouts thoroughly. Consider using the `style_map` option for fine-grained control over how CSS classes map to Word styles.
affects: All versions
gotchaBy default, tables in the output DOCX will not have any specific styling (e.g., borders).
fix
Set the `table_style` attribute on the `HtmlToDocx` parser instance to apply a predefined Word table style, for example: `parser.table_style = 'Table Grid'`.
affects: All versions
gotchaIf you are using `python-docx` templates with custom styles, these custom styles will not be present if you initialize `document = Document()` without loading the template. This can lead to missing styles when adding HTML content.
fix
Always load your template if it contains custom styles: `document = Document('your_template.docx')`. Ensure any referenced custom styles exist in the document at generation time; warnings will be logged for missing styles.
affects: All versions
Errors
Common errors & fixes
FileNotFoundError: [Errno 2] No such file or directory: 'your_file_name.docx'
The specified output DOCX file path is invalid, or the directory where the file is supposed to be saved does not exist.
fix
Ensure that the directory path for the output `.docx` file already exists, or provide a full absolute path. Python's `os.makedirs()` can be used to create directories if needed.
Tables are not showing borders or other expected styles in the output DOCX.
The `html-for-docx` library does not apply default styles to tables.
fix
Set the `table_style` attribute on your `HtmlToDocx` parser instance before processing, e.g., `parser = HtmlToDocx(table_style='Table Grid')` or `parser.table_style = 'Light Shading Accent 1'`. Refer to `python-docx` documentation or Word itself for available table style names.
Specific HTML tags or inline CSS styles (e.g., `color`, `font-size`) are not being applied, or render incorrectly in the DOCX output.
The library might not support all CSS properties, or there could be style precedence issues. Check the documentation for currently supported properties.
fix
Consult the `html-for-docx` documentation for the list of supported HTML tags and CSS properties. For custom class-based styling, use the `style_map` option. For highest precedence, apply inline CSS with `!important`.
Crash or incorrect rendering when processing images with RGBA color profiles.
Older versions (prior to 1.1.3) had a bug handling specific image formats, notably those with RGBA color profiles.
fix
Upgrade `html-for-docx` to version 1.1.3 or higher, as this specific bug was fixed in that release.
Upgrade
Version history
1.1.5latest on PyPI · released Apr 17, 2026
Audit
Dependencies
python-docxrequiredCore functionality relies on `python-docx` for creating and manipulating Word documents.
BeautifulSoup4requiredUsed internally for parsing and fixing HTML content, especially when the `Disable Fix-HTML` option is not enabled.
Agent activity
77 hits · last 30 days
node
74
Resources
html-for-docx — pip install html-for-docx · libregistry