Library / SDK
Python-Markdown/markdown avatar
Python-Markdown/markdown

Python-Markdown's real floor is Python 3.11, not the pip line

A Python implementation of John Gruber’s Markdown with Extension support.

4,258 stars932 forksPythonBSD-3-Clause

At a glance

What is it?
Python-Markdown describes itself as almost completely compliant with the reference implementation while pointing readers elsewhere for what it does not match. The packaging metadata is where the decisions that bite sit: a 3.11 floor, a distribution name with a capital letter, a dynamic version and two spellings of one maintainer's name.
Who is it for?
This library fits a Python project that needs Markdown conversion with the reference syntax handled for you and can live with Python 3.11 as its floor, on CPython or PyPy. It does not fit a codebase still on an older interpreter, since the metadata requirement excludes anything below 3.11 while the install line says nothing about it.
Can I use it commercially?
Yes. BSD-3-Clause is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 3 days ago.
What is it written in?
Mainly Python, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 14, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • Python-Markdown/markdown4,258 ★ · +8
Star history
Repository2026-09-232026-11-14
Python-Markdown/markdown4.3k4.3k

8 Stars in the last 52 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

Almost completely compliant, with the gaps kept off the page

The compatibility claim is the project's own wording: almost completely compliant with the reference implementation, though there are a few known issues. It does not stop there. Readers are sent to a Features page for information on exactly what is supported and what is not, and to a separate extensions page for everything beyond the base syntax.

So the honest summary of this library's scope is split across three destinations. The reference syntax, the documented deviations from it, and the extensions that add the rest.

That arrangement is worth knowing about before you write a conformance test suite. A behaviour that surprises you may not be a bug in your integration, since matching the reference implementation is stated as an aim rather than a guarantee.

The Python floor is declared in the metadata, not the install line

The whole install instruction is one line.

bash
pip install markdown

The metadata behind that line is where the constraint lives. The project requires Python 3.11 or newer, and the classifier list enumerates 3.11, 3.12, 3.13, 3.14 and 3.15, with both CPython and PyPy named as implementations.

A machine on a future 3.16 is outside the tested range the classifiers advertise, though nothing in the requirement field blocks it.

The README also points at the `docs/` directory of the distribution and the project website for installation and usage detail, so the one-line version is the summary rather than the manual.

The distribution is Markdown, the import is markdown

Two names are in play and they differ by case. The project name in the packaging metadata is `Markdown`, while the import in the usage example is lowercase.

python
import markdown
html = markdown.markdown(your_text_string)

That is why the install line uses the lowercase form and still lands on the right distribution. It also means anything that records a package name, a requirements line or a lockfile will show the capitalised version, while your code always writes the lowercase one.

The version is not in the file at all. It is declared dynamic, which means the number comes from somewhere inside the package rather than from the manifest, and the tag you install by is decided at release time. Release 3.11.0 was published on 2026-09-25.

The author list and the maintainer list spell one name differently

The metadata carries two separate name lists and they are not the same set.

Three names appear as authors: Manfred Stienstra, Yuri Takhteyev and Waylan limberg. Two appear as maintainers: Waylan Limberg and Isaac Muse. The third name is the same person written with a lowercase l in one list and a capital L in the other, which is the kind of thing that survives for years because packaging tools treat it as a free-form string.

The sets overlap in one entry only, so Isaac Muse is credited as a maintainer without being listed as an author, and the first two names appear as authors without being listed as maintainers. A contact address is attached to Waylan in both lists.

None of this breaks an install. It does mean that if you are looking for who to contact about a release, the maintainer list is the one to read, and it is shorter than the author list.

Coverage is configured twice and prose is spell checked

Testing and documentation quality are both wired into the repository rather than left to convention.

There are two coverage configuration files, `.codecov.yml` and `.coveragerc`, and a coverage badge whose link is pinned to the master branch, which is also the default branch. Running both a repository-level and a tool-level configuration is not redundant in practice, since they answer different questions about what gets measured.

Prose gets the same treatment. `.pyspelling.yml` configures a spell checker and `.spell-dict` is the project dictionary beside it, so words that are legitimately part of the documentation are listed rather than ignored inline.

The build badge points at a workflow file named tox.yml, which is also the hint about how the test matrix runs.

Documentation has two configurations and a link checker

The documentation output is built from more than one toolchain, and the repository verifies its own links.

`mkdocs.yml` sits at the top level as the primary configuration, and a `.zensical/` directory sits beside it, so there are two sets of documentation configuration present at once. Which one produces the published site is not stated in the README, and that ambiguity matters if you fork the project and want the same site.

`checklinks.sh` is a separate script for verifying links, and the README points to the change log on the project website.

The `docs/` directory is also the distribution's own documentation, which the installation notes point to for advanced usage. The same text therefore serves two audiences: people reading the website and people reading an installed package.

tox drives the tests while uv.lock sits beside pip instructions

The build tooling around the library is worth listing because it is more than one system.

`tox.ini` is the test configuration the badge refers to. A lowercase `makefile` sits next to it for the usual task shortcuts. `tests/` and `tools/` are both present as directories, and `MANIFEST.in` governs which files are packaged.

Then there is `uv.lock` at the top level. The instructions tell you to install with pip, and the repository carries a lockfile from a different tool, which means the dependency set is pinned somewhere that a plain pip install does not read.

`.gitattributes`, `.gitignore` and `CODE_OF_CONDUCT.md` complete the top level, and the behaviour expected of everyone in the issue trackers and mailing lists is set out in that last file.

Three releases in eight months and 23 open issues

The release line gives a clear picture of the cadence. Version 3.11.0 was published on 2026-09-25, 3.11.1 on 2026-10-13, and 3.11.2 on 2026-10-19. The first was a minor bump and the next two were patches.

The repository numbers are 4,257 stars, 929 forks and 26 open issues, on the master branch, with the last push dated 2026-10-29.

Twenty-six open issues against that star count is a low number, and the fork count is high relative to it. Both are consistent with the pattern you would expect from a library that most people install rather than modify, where the reports that do arrive tend to be about a specific document rather than about the library.

Editorial conclusion

This library fits a Python project that needs Markdown conversion with the reference syntax handled for you and can live with Python 3.11 as its floor, on CPython or PyPy. It does not fit a codebase still on an older interpreter, since the metadata requirement excludes anything below 3.11 while the install line says nothing about it. Before you pin it, check four things. Your interpreter version, because the floor is declared in the metadata and not in the installation instructions. Which behaviours you actually rely on, since the project's own claim of being almost completely compliant comes with a separate page enumerating the gaps. Whether you need anything outside the base syntax, since the extra features are extensions documented on their own page. And what the import name versus the distribution name will do to your lockfile, since one is `Markdown` and the other is `markdown`.

Frequently asked questions

How do I install Python-Markdown?

The install command given in the project documentation is pip install markdown. The package is published on PyPI under the name Markdown, and the import in your own code is the lowercase markdown. The distribution also ships a docs/ directory with fuller installation and usage material.

What Python versions does Python-Markdown support?

The packaging metadata requires Python 3.11 or newer, and the published classifiers list 3.11 through 3.15 with both CPython and PyPy named as implementations. Anything below 3.11 is outside the declared requirement.

Is Python-Markdown identical to John Gruber's reference Markdown?

The project describes itself as almost completely compliant with the reference implementation, with a few known issues, and points to a Features page for what is supported and what is not. Extra behaviour beyond the reference syntax is provided through extensions documented separately.

Official sources

  1. License: BSD-3-Clause
  2. Project website
  3. Python-Markdown/markdown on GitHub
  4. README
  5. Releases
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/python-markdown-markdown.svg)](https://hysenlabs.com/projects/python-markdown-markdown)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/python-markdown-markdown.svg)](https://hysenlabs.com/projects/python-markdown-markdown)

Was this useful?