Parser Comparison

Choosing a Python Markdown parser is a tradeoff. This page compares Patitas with the three most common alternatives — markdown-it-py, Python-Markdown, and mistune — so you can decide which fits your project.

The goal here is to be honest, not to win every row. Patitas explicitly does not try to beat mistune or markdown-it-py on raw single-thread speed (see Explicitly Not Planned below). It optimizes for safety, typing, and free-threading instead.

At a Glance

The percentages and pass counts above are tracked in the repo (see GFM compliance tracking) rather than asserted as marketing claims.

Python Version and Free-Threading

This is the sharpest line between Patitas and everything else.

• Patitas is Python 3.14+ only. Supporting older versions would compromise the free-threading and modern-syntax design, so it is explicitly not planned.
• AST nodes are frozen, slotted dataclasses, and parser/renderer configuration is held in aContextVarrather than on shared mutable instance state. A singleMarkdowninstance is safe to reuse across free-threaded (3.14t) workers, andMarkdown.parse_many(...)exists for batch workloads.
• markdown-it-py, Python-Markdown, and mistune all predate free-threading and configure a mutable parser instance, so they are not designed to be shared across no-GIL threads.

See Thread Safety for the full design.

Standards Compliance

• Patitas targets CommonMark 0.31.2 and additionally measures GFM 0.29 compliance with the GFM plugins enabled. Both pass rates are tracked as ratchets in the test suite so they cannot silently regress.
• markdown-it-py is CommonMark compliant by design (it is a port of the reference JavaScriptmarkdown-it).
• Python-Markdown implements its own historical dialect, not CommonMark.
• mistune is fast and popular but follows its own dialect rather than the full CommonMark spec.

Typed AST vs Tokens vs Trees

Each parser exposes its parse result differently:

• Patitas — a typed, immutable tree of dataclasses (Document, Heading, Paragraph, ...). You get isinstancenarrowing, IDE autocomplete, and compile-time type checking, plusto_dict() / to_json()serialization and BaseVisitor / transformfor traversal.
• markdown-it-py — a flat list ofTokenobjects walked with nesting/typebookkeeping.
• Python-Markdown — anxml.etree.ElementTree, manipulated with treeprocessors.
• mistune — nesteddict[str, Any]structures.

If your pipeline does AST analysis or transformation (linting, link rewriting, excerpts, LLM preprocessing), the typed tree is the main reason to pick Patitas.

Extensibility

Patitas extension handlers are required to be stateless and registry-driven, which is what keeps a configuredMarkdowninstance safe to share across threads.

Security

The default renderers of Patitas, markdown-it-py (html: True), and mistune (escape=False) are all CommonMark-style: raw HTML and javascript:/data: URLs pass through. Patitas does not silently strip them — instead it offers an AST-levelsanitize() step with policies (for example web_safe) that you apply before rendering untrusted input:

from patitas import parse, sanitize, render
from patitas.sanitize import web_safe

doc = parse(untrusted_source)
html = render(sanitize(doc, policy=web_safe))

Patitas's lexer is also hand-written and runs in guaranteed O(n) with no regex backtracking, which removes a class of ReDoS risks that regex-driven parsers can carry. See Security.

Migration Effort

When to Choose Which

• Choose Patitas if you are on Python 3.14+, want a typed/immutable AST, care about free-threading or incremental re-parsing, or want MyST directives without extra packages.
• Choose markdown-it-py if you need CommonMark on older Python versions or already live in the MyST/Sphinx ecosystem.
• Choose Python-Markdown if you depend on its long-standing extension ecosystem and its specific dialect.
• Choose mistune if raw single-thread throughput on a known-trusted dialect is your top priority.

A Note on Honesty

Patitas's ROADMAP explicitly lists what it will not do:

• Beating mistune on raw single-thread speed — the FSM architecture has a floor; on the full CommonMark spec the gap is small and imperceptible for typical documents. Effort goes to safety, threading, typed AST, and incremental parsing instead.
• A Python-Markdown compatibility layer — different spec, API, and audience.
• Python < 3.14 support — free-threading and modern syntax are core to the design.

For current numbers, run the bundled benchmarks yourself rather than trusting a static table:

uv pip install mistune markdown-it-py
python benchmarks/benchmark_vs_mistune.py