Registry / serialization / html-to-markdown

html-to-markdown

library3.6.1pypypi✓ verified 85d ago

html-to-markdown is a high-performance Python library for converting HTML to Markdown, powered by a Rust core. Currently at version 3.1.0, it offers a clean Python API and aims for consistent output across multiple language bindings. The library is actively maintained with ongoing development and performance enhancements.

serialization http-networking data

pip install html-to-markdown

github ↗package ↗

INSTALL

IMPORT

SIG · HTML-TO-MARKDOWN

html-to-markdown

serializationpythonv3.6.1

Install

2.0s avg

Import

30ms

Disk

26MB

Pass rate

3/ 10

Env Coverage3 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v3.6.1 · 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

glibc

py 3.10

✕ build_error

✓ 1.83s

py 3.11

✕ build_error

2/4 runs

py 3.12

✕ build_error

2/4 runs

py 3.13

✕ build_error

2/4 runs

py 3.9

✓ —

✓ 2.2s

26MB installed

● package 26MB

Code

Verified usage

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

convert

✓ from html_to_markdown import convert

Primary function for basic HTML to Markdown conversion.

ConversionOptions

✓ from html_to_markdown import ConversionOptions

Used to customize conversion behavior (e.g., heading style, output format).

convert_with_metadata

✓ from html_to_markdown import convert_with_metadata

Use to extract Markdown content along with structured metadata (headers, links, images).

This quickstart demonstrates basic HTML to Markdown conversion using the `convert` function. It also shows how to apply `ConversionOptions` to customize the output format, such as specifying heading styles or using Djot instead of standard Markdown.

from html_to_markdown import convert, ConversionOptions html_content = """ <h1>Welcome</h1> <p>This is <strong>bold</strong> and <em>italic</em> text.</p> <ul> <li>Item 1</li> <li>Item 2</li> </ul> """ # Basic conversion markdown_output = convert(html_content) print(f"Default Markdown:\n{markdown_output}") # Conversion with options options = ConversionOptions( heading_style="atx", list_indent_width=2, output_format="commonmark" ) formatted_markdown = convert(html_content, options) print(f"\nFormatted Markdown (CommonMark):\n{formatted_markdown}") # Example for Djot output (another lightweight markup language) djot_options = ConversionOptions(output_format="djot") djot_output = convert(html_content, djot_options) print(f"\nDjot Output:\n{djot_output}")

Debug

Known issues

breakingVersion 2.x introduced a complete rewrite with a Rust core, leading to significant performance gains but also breaking changes in the API. While a `v1_compat` module was provided, users upgrading from 1.x should review the changelog for necessary code adjustments.

fix

Consult the library's CHANGELOG for specific migration steps. Consider using `html_to_markdown.v1_compat` if direct migration is complex.

affects: <2.0.0 to 2.x.x+

gotchaMarkdown is a less expressive format than HTML. Complex HTML structures, inline styles, and certain advanced tags (e.g., `<script>`, `<style>`) will be simplified or entirely removed during conversion, potentially leading to a loss of original formatting or functionality.

fix

Pre-process HTML with a tool like BeautifulSoup to simplify or strip unwanted elements before conversion. Review converted Markdown carefully for fidelity.

affects: All versions

gotchaConversion of complex HTML tables (e.g., with `colspan`, `rowspan`, nested elements) and `<code>`/`<pre>` blocks might not perfectly retain original formatting or indentation in Markdown. This can lead to less readable or incorrectly structured output.

fix

For critical code blocks or tables, manually verify the output. Consider using the 'Visitor Pattern' feature (`convert_with_visitor`) for fine-grained control over specific element conversions, especially for `pre` and `code` tags.

affects: All versions

gotchaThe primary `convert()` function only returns the Markdown string. If you need to extract structured metadata like titles, links, or headings from the HTML during conversion, you must use `convert_with_metadata()` which returns a dictionary including both content and metadata.

fix

Use `from html_to_markdown import convert_with_metadata` and process the returned dictionary, e.g., `result = convert_with_metadata(html_content); markdown_content = result['content']; metadata = result['metadata']`.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'html_to_markdown'

The 'html-to-markdown' Python package is not installed in the current environment or the package name is misspelled in the import statement.

fix

Ensure the package is correctly installed using pip: `pip install html-to-markdown`

TypeError: 'module' object is not callable

The user is attempting to call the 'html_to_markdown' module directly as a function instead of calling the `convert` function provided by the module.

fix

Import the `convert` function specifically and use it to perform the conversion: `from html_to_markdown import convert
markdown = convert(html_content)`

Unexpected/Incomplete Markdown output for complex HTML structures (e.g., tables, figures, scripts)

The default conversion rules of `html-to-markdown` may not fully support or accurately translate highly complex HTML elements, specific inline styles, or non-standard tags into a precise Markdown equivalent, often stripping unsupported elements or simplifying structures.

fix

Review the library's documentation for `ConversionOptions` and `visitor` patterns to customize conversion behavior. For very complex or problematic HTML, consider preprocessing the HTML with a library like BeautifulSoup to simplify it before passing to `html-to-markdown`, or handling specific elements with custom logic during conversion.

Upgrade

Version history

3.6.1latest on PyPI · released Jun 12, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

12 hits · last 30 days

node

Resources

githubhttps://github.com/kreuzberg-dev/html-to-markdown ↗

packagehttps://pypi.org/project/html-to-markdown/ ↗