Install & Compatibility
Where this runs
tested against v0.9.2 · 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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.130s · 18.3MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.6s · import 0.122s · 19MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
commonmark
✓ from commonmark import commonmark
For direct conversion of Markdown string to HTML.
Parser, HtmlRenderer
✓ from commonmark import Parser, HtmlRenderer
✗ import CommonMark
The top-level 'CommonMark' module was removed in version 0.8.1. You must now use 'import commonmark' or import specific components like 'Parser' and 'HtmlRenderer' from the 'commonmark' package. [10]
This quickstart demonstrates both the simple `commonmark.commonmark()` function for direct conversion and the more advanced `Parser` and `HtmlRenderer` classes for parsing to an AST and then rendering to HTML. [5, 7]
import commonmark
from commonmark import Parser, HtmlRenderer
markdown_text = "Hello *World*! This is **CommonMark**."
# Simple conversion
html_output_simple = commonmark.commonmark(markdown_text)
print(f"Simple HTML:\n{html_output_simple}")
# Advanced usage with AST manipulation
parser = Parser()
ast = parser.parse(markdown_text)
renderer = HtmlRenderer()
html_output_advanced = renderer.render(ast)
print(f"\nAdvanced HTML:\n{html_output_advanced}")
# Example of AST inspection (prints a tree structure)
# commonmark.dumpAST(ast)
commonmark --version
Debug
Known issues
deprecatedThe commonmark.py project is no longer actively maintained and has been officially deprecated. The maintainers recommend migrating to `markdown-it-py` for new projects or existing ones. [7]fixConsider migrating to `markdown-it-py`. If continuing with `commonmark`, be aware of potential lack of future updates or security fixes.
affects: 0.9.1 and later
breakingThe package and module name changed from `CommonMark` to `commonmark` for PEP8 compliance in version 0.8.0. While 0.8.0 allowed both `import commonmark` and `import CommonMark`, the symlink for `CommonMark` was removed in 0.8.1. This means code using `import CommonMark` will break when upgrading to 0.8.1 or later. [10, 12]fixReplace all instances of `import CommonMark` with `import commonmark` and update any references to `CommonMark.some_function` to `commonmark.some_function`.
affects: >=0.8.1
gotchaFor Python 2 compatibility in version 0.9.1, the `future` library (>=0.14.0) is a required dependency. Users on Python 2 environments should ensure this dependency is installed. The project's testing covered Python 2.7, 3.5-3.8. [0.9.1 release notes, 7]fixEnsure `pip install commonmark[py2]` or `pip install commonmark future` is used when installing on Python 2.
affects: 0.9.1 (Python 2 environments)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'CommonMark'
In versions prior to 0.8.0, the commonmark library used 'CommonMark' (capitalized) as its module name, which was later changed to 'commonmark' (lowercase) causing import errors in updated environments.
fixUpdate your import statements from `import CommonMark` to `import commonmark` and ensure the installed package is `commonmark`.
AttributeError: 'HTMLParser' object has no attribute 'unescape'
This error occurs when commonmark.py is run with Python versions 3.9 or higher, as the `unescape` method of `html.parser.HTMLParser` was deprecated in Python 3.4 and removed in Python 3.9.
fixEither use a Python version older than 3.9 or migrate to an actively maintained CommonMark parser like `markdown-it-py`, as commonmark.py is deprecated.
commonmark.py deprecated
The `commonmark.py` project is officially deprecated and is no longer actively maintained, meaning it will not receive updates for new Python versions, bug fixes, or new features.
fixIt is highly recommended to migrate to `markdown-it-py`, which is the actively maintained and recommended alternative for CommonMark parsing in Python.
Upgrade
Version history
0.9.2latest on PyPI · released May 28, 2026
Audit
Dependencies
futureoptionalRequired for Python 2 compatibility (version 0.9.1 requires future >= 0.14.0 on Python 2). [0.9.1 release notes]