---
id: html-to-markdown
version: "3.10.6"
license: MIT
license_treatment: permissive
maintenance: active
---

# html-to-markdown — High-performance HTML to Markdown converter

License: permissive · Maintenance: active · Downloads: 830.0K/mo

## What it is and what it does

html-to-markdown is a Python binding to a Rust-based HTML-to-Markdown converter designed to handle messy, real-world HTML without requiring manual parsing strategy selection or tuning. It accepts unclosed tags, malformed entities, CDATA, custom elements, nested tables, and mixed encodings, then returns clean Markdown output in a single `convert()` call. The package exposes a structured result containing the converted content, warnings, and optionally extracted metadata (Open Graph, Twitter, JSON-LD, microdata).

The converter uses a tiered dispatch strategy (byte scanner → DOM walker → html5ever repair) to achieve byte-equal output across different parsing paths, ensuring consistent results regardless of input complexity. It supports both CommonMark and Djot output formats, handles GitHub-flavored Markdown tables with alignment and cell padding, and can optionally mirror inline images. The implementation is fast enough for whole-corpus jobs and requires Python 3.10 or later; it ships as a compiled extension with pre-built wheels for major platforms.

Use it for:

- Extract clean Markdown from web scraped HTML without manual cleanup or tag-balancing logic.
- Convert email HTML bodies or rich-text editor output to Markdown for storage or downstream processing.
- Parse and extract structured metadata (Open Graph, JSON-LD) from web pages in the same pass as content conversion.
- Build content pipelines that accept arbitrary HTML and produce consistent, lossless Markdown without tuning per-source.
- Generate Markdown documentation from HTML-based CMS exports or legacy web content archives.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Converts real-world HTML—including malformed tags, broken entities, and nested tables—into clean CommonMark or Djot Markdown in a single call, with optional metadata extraction.

Yes. The package is actively maintained, has no known vulnerabilities, supports current Python versions (3.10–3.14), and solves a real problem—converting messy HTML to clean Markdown without manual intervention. Medium install friction is acceptable for a compiled extension with pre-built wheels. Use it if you need robust HTML-to-Markdown conversion in production; skip it only if you need Python <3.10 or have a simpler, pure-Python alternative already in place.

## Install

pip install html-to-markdown
uv add html-to-markdown
poetry add html-to-markdown

## Installing html-to-markdown

Before you install: Medium install friction due to compiled wheels (cp310-abi3 binaries for multiple platforms), but pre-built for common architectures (x86_64, aarch64, macOS, Windows). Active maintenance with a release 9 days old and 845 repository stars.

License in practice: MIT license permits unrestricted use, modification, and distribution in commercial and private projects with minimal attribution requirements.

Quickstart:

pip install html-to-markdown

from html_to_markdown import convert

result = convert('<p>Hello <b>world</b></p>')
print(result['content'])  # Hello **world**

Requires Python 3.10 or later; compiled extension wheels are platform-specific but pre-built for x86_64, aarch64, macOS, and Windows.

Verify before relying:

- Whether the visitor API and metadata extraction features are exposed in the Python binding or require direct Rust access.
- Performance characteristics (19–116 MB/s cited for corpus) on typical document sizes in production Python workflows.
- Whether Djot output format is fully supported in the Python package or limited to CommonMark.

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: medium
- Maintenance: active
- Downloads: 830.0K/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

html to markdown converter, convert html to markdown, html markdown transformation, clean markdown from html, html parser markdown output, robust html conversion, markdown generation from web content, html-parsing, markdown-generation, content-extraction

[View on SkillFed](https://skillfed.io/packages/html-to-markdown) · [View on PyPI](https://pypi.org/project/html-to-markdown/)