mdformat

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 on this page — 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

mdformat on PyPI

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

Evidence: mdformat-1.0.0-py3-none-any.whl

Keywords: mdformat, markdown, commonmark, formatter, pre-commit

Tags

More Python Modules packages