Skip to content
markdown→html

Developer Guide

Convert Markdown to HTML in Python

Convert Markdown to HTML in Python with the markdown package. Install it with pip, then call markdown.markdown() with a Markdown string to return HTML. Enable GitHub-style features such as tables through the extensions argument.

Key facts

Primary library
markdown (Python-Markdown)
Core call
markdown.markdown(text)
GitHub-style features
via extensions=["tables", "fenced_code"]
Install
pip install markdown

How do you convert Markdown to HTML in Python?

Install the markdown package with pip install markdown, then call markdown.markdown() with a Markdown string. It returns an HTML string. The markdown package is the reference Python implementation of Markdown.

The single function call covers standard Markdown. For the methods overview across languages and tools, see How to Convert Markdown to HTML.

markdown
import markdown

html = markdown.markdown("# Hello")
# "<h1>Hello</h1>"
html
<h1>Hello</h1>

How do you convert a Markdown file?

Open the file, read its contents into a string, then pass that string to markdown.markdown(). Read the file as UTF-8 so non-ASCII characters convert correctly. The function returns the HTML string.

markdown
import markdown

with open("input.md", "r", encoding="utf-8") as f:
    text = f.read()

html = markdown.markdown(text)

How do you enable tables and fenced code blocks?

Pass an extensions list to markdown.markdown(). The markdown package keeps GitHub-style features as opt-in extensions, so add tables and fenced_code explicitly: markdown.markdown(text, extensions=["tables", "fenced_code"]).

This opt-in model differs from JavaScript's marked, where GitHub Flavored Markdown is on by default. Add only the extensions you need.

markdown
html = markdown.markdown(
    text,
    extensions=["tables", "fenced_code"],
)

How does markdown2 compare?

markdown2 is an alternative single-file library. Call markdown2.markdown() with a Markdown string to return HTML. It bundles several extras differently, but the core string-in, HTML-out call is the same shape.

Choose the markdown package for its mature extension ecosystem, or markdown2 for a lighter single-file dependency.

markdown
import markdown2

html = markdown2.markdown("# Hello")
html
<h1>Hello</h1>

Frequently Asked Questions

What is the difference between markdown and markdown2?
Both convert a Markdown string to HTML in one call. The markdown package has a large extension ecosystem and configurable output; markdown2 is a single file with extras enabled differently. Either works for standard conversion.
How do I get tables in the output?
Tables are an extension in the markdown package. Pass extensions=["tables"] to markdown.markdown(). Without it, pipe-table syntax is left as literal text rather than converted to an HTML table.
Does the markdown package sanitize HTML?
No. The old safe_mode option was removed, so the markdown package does not sanitize output. Sanitize the resulting HTML with a maintained sanitizer such as nh3 when the Markdown comes from untrusted users.
Which Python versions are supported?
The markdown package supports current CPython releases and PyPy. Install the latest version with pip install markdown to get support for actively maintained Python versions.