---
id: mdformat
version: "1.0.0"
license: MIT
license_treatment: permissive
maintenance: active
---

# mdformat — CommonMark compliant Markdown formatter

License: permissive · Maintenance: active · Downloads: 2.9M/mo

## What it is and what it does

Mdformat is a pure-Python Markdown formatter built on the markdown-it parser that enforces CommonMark compliance across your Markdown files. It works as both a standalone command-line tool and a Python library, making it suitable for CI/CD pipelines, pre-commit hooks, and programmatic use. The formatter is opinionated about style—it normalizes formatting to a single canonical form—and validates that its changes don't alter the rendered HTML output.

The tool supports extensibility through plugins for non-CommonMark dialects like GitHub Flavored Markdown, MyST, and others. It can format files in place, check formatting without modifying files, and read from stdin. Unlike Node.js-based alternatives, mdformat requires no additional runtime beyond Python itself, making it lightweight for Docker images and environments where Python is already available.

Use it for:

- Enforce consistent Markdown style across a documentation repository as part of CI/CD or pre-commit hooks.
- Format Markdown files in bulk before committing to version control to maintain a uniform code style.
- Validate that Markdown files conform to CommonMark specification without altering their rendered meaning.
- Integrate Markdown formatting into Python-based documentation generation or build pipelines.
- Check Markdown formatting in pull requests without applying changes, using the --check flag.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Mdformat is a CommonMark-compliant command-line Markdown formatter and Python library that enforces consistent style across Markdown files.

Yes. Mdformat is actively maintained, has minimal dependencies, supports current Python versions, carries no known vulnerabilities, and is MIT-licensed. It is well-suited for projects that need CommonMark-compliant Markdown formatting in CI/CD or as a pre-commit hook. Install it if you want a lightweight, pure-Python formatter; consider its plugin ecosystem if you need support for non-CommonMark dialects.

## Install

pip install mdformat
uv add mdformat
poetry add mdformat

## Installing mdformat

Before you install: Low install friction with only two runtime dependencies (markdown-it-py and tomli). The project is actively maintained with a recent commit on 2026-08-10 and supports current Python versions (requires Python 3.10+).

License in practice: MIT license permits free use, modification, and distribution with minimal restrictions—suitable for both open-source and commercial projects.

Quickstart:

pip install mdformat

mdformat README.md

# Or check without modifying:
mdformat --check README.md

# Or use as a library:
from mdformat import text
formatted = text("# Hello\n\nWorld")

Requires Python 3.10 or later. The --exclude option is only available on Python 3.13+.

Verify before relying:

- Whether the package's plugin ecosystem (mdformat-gfm, mdformat-myst, etc.) is actively maintained and widely adopted.
- Performance characteristics when formatting large Markdown files or directories with thousands of files.
- How well the formatter handles edge cases in real-world Markdown that mixes CommonMark with custom syntax.

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 2.9M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

markdown formatter commonmark, format markdown files, markdown style enforcer, markdown linter formatter, commonmark compliant formatter, markdown code formatter, pre-commit markdown tool, markdown consistency checker, markdown-formatter, commonmark, cli-tool

[View on SkillFed](https://skillfed.io/packages/mdformat) · [View on PyPI](https://pypi.org/project/mdformat/)