pyhtml2text

Fast HTML to plain text and to Markdown for Python, built on rust-html2text.

Relative links can be resolved against the page's URL, so the output's links work on their own.

Markdown

from pyhtml2text import html2markdown

html = """<h2>Before you start</h2>
<p>Read the <a href="setup.html">setup guide</a> and <b>back up</b> your data.</p>
<img src="/img/diagram.png" alt="How it fits together">
<table><tr><th>Plan</th><th>Price</th></tr><tr><td>Basic</td><td>Free</td></tr></table>"""

print(html2markdown(html, base_url="https://example.com/docs/intro.html"))

## Before you start

Read the [setup guide](https://example.com/docs/setup.html) and **back up** your data.

![How it fits together](https://example.com/img/diagram.png)

| Plan | Price |
| --- | --- |
| Basic | Free |

html2markdown(html, *, base_url=None) writes CommonMark with GitHub's tables and strikethrough, in the usual conventions:

• # headings, - bullets, _emphasis_ and **strong**, ~~strikethrough~~.
• Inline links and images, [text](url) and ![alt](src), made absolute when base_url is given. A link whose only content is an icon uses its aria-label or title as its text.
• Fenced code blocks, tagged with the language when the page names one (class="language-python").
• Pipe tables. Cells spanning rows or columns become empty cells, a table without a header row gets an empty one, and tables used for page layout are written as plain paragraphs.
• Characters are escaped only where Markdown would otherwise read them as syntax, so snake_case, 5 * 3 and $5 stay as they are.
• Lines aren't wrapped. Hidden content (hidden, aria-hidden, display: none), scripts, styles and form controls are left out.

The output is checked by rendering it back with a CommonMark parser and comparing every word, link and image with the original page, on real sites and on tens of thousands of random documents (tests/markdown_check.py).

Plain text

from pyhtml2text import html2text

html = '<p>Please <a href="/login">sign in</a> first.</p>'

print(html2text(html, base_url="https://example.com/docs/page.html"))
# Please [sign in][1] first.
#
# [1]: https://example.com/login

html2text(html, width=80, *, ...)

Both functions take a str or UTF-8 bytes (e.g. response.content). Requires Python 3.10 or later.

Performance

Median time on an Apple Silicon Mac. To Markdown:

To plain text:

• The GIL is released while converting, so threads scale across cores. On free-threaded Python (3.14t) the module runs without re-enabling the GIL.
• Wheels for Linux (x86_64, aarch64), macOS and Windows x64 are built with profile-guided optimisation, which makes them about 25% faster. Other platforms get the same code without it.
• Deeply nested HTML is parsed in linear time, so hostile input can't stall a worker: 40,000 nested lists take 0.14 s, against 6 s with stock html5ever, and 100,000 levels of nesting followed by unmatched end tags take under 0.1 s.

Credits

The plain-text rendering is done by rust-html2text by Chris Emerson (MIT). This package uses a fork that adds base_url and some performance changes, and a copy of html5ever (MIT/Apache-2.0) with servo/html5ever#800 by Josef Guenther applied, which makes parsing deeply nested HTML linear (see vendor/). Markdown output is checked with pulldown-cmark (MIT). It isn't affiliated with or endorsed by any of these projects, so please report issues here rather than upstream.