Registry / testing / mdformat

mdformat

JSON →
library1.0.0pypypi✓ verified 24d ago

Mdformat is an opinionated Markdown formatter that can be used to enforce a consistent style in Markdown files. It functions as both a Unix-style command-line tool and a Python library. The current stable version is 1.0.0, and it features an extensible plugin system to support various Markdown extensions and embedded code formatting. The project maintains an active release cadence, with version 1.0.0 released after several minor versions, indicating ongoing development and maintenance.

pip install mdformat
INSTALL
IMPORT
SIG · MDFORMAT
M
mdformat
testingpythonv1.0.0
Install
2.0s avg
Import
112ms
Disk
23MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.0.0 · 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
musl
py 3.103.910 runs
installs and imports cleanly · install 0.0s · import 0.116s · 27.1MB
glibc
py 3.103.910 runs
installs and imports cleanly · install 2.0s · import 0.107s · 28MB
23MB installed
● package 23MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

mdformat
import mdformat

This quickstart demonstrates how to use `mdformat.text()` to format a Markdown string directly. It also shows how to apply formatting options like numbering ordered lists and setting word wrap width. For file-based formatting, `mdformat.file()` can be used, which modifies the file in place.

import mdformat unformatted_markdown = """ # A Header This is some **unformatted** text. - List item 1 - List item 2 """ formatted_markdown = mdformat.text(unformatted_markdown) print("--- Unformatted ---") print(unformatted_markdown) print("\n--- Formatted ---") print(formatted_markdown) # Example with options formatted_with_options = mdformat.text( "- One\n- Two\n- Three", options={ "number": True, # Apply consecutive numbering to ordered lists "wrap": 60 # Set word wrap width to 60 characters } ) print("\n--- Formatted with Options ---") print(formatted_with_options) # To format a file in place (requires a file to exist): # with open("test.md", "w") as f: # f.write(unformatted_markdown) # mdformat.file("test.md") # with open("test.md", "r") as f: # print("\n--- Formatted File ---") # print(f.read())
mdformat --version
Debug
Known issues
breakingmdformat 1.0.0 removed official support for Python 3.9. Users should upgrade to Python 3.10 or newer.
fix
Upgrade your Python environment to version 3.10 or later.
affects: >=1.0.0
gotchaThe exact formatting style produced by `mdformat` is not guaranteed to be stable across major or even minor versions. It is highly recommended to pin the `mdformat` dependency version in your project to ensure consistent formatting.
fix
Pin the `mdformat` version in your `requirements.txt` or `pyproject.toml` (e.g., `mdformat==1.0.0`).
affects: All versions
gotcha`mdformat` is a CommonMark formatter by default. It may backslash-escape syntax extensions (e.g., GitHub Flavored Markdown, MkDocs, Hugo) that are not part of the CommonMark specification to ensure formatting changes do not alter the rendered document. For proper formatting of extended Markdown, install and enable relevant plugins (e.g., `mdformat-gfm`).
fix
Install and configure specific `mdformat` plugins (e.g., `pip install mdformat-gfm`) to handle non-CommonMark syntax extensions.
affects: All versions
breakingThe plugin API has undergone changes, specifically in version 1.0.0. For instance, `mdformat.plugins.ParserExtensionInterface.add_cli_options` was removed (deprecated since 0.7.19) and replaced by `mdformat.plugins.ParserExtensionInterface.add_cli_argument_group`. Plugins developed for older versions might break.
fix
Update custom plugins to conform to the latest plugin API, or check for updated versions of third-party plugins.
affects: >=1.0.0
gotcha`mdformat` includes a safety check that errors if the formatted Markdown renders to different HTML than the input Markdown (`Formatted Markdown renders to different HTML than input Markdown`). While this protects against accidental content changes, it can sometimes trigger false positives, especially with certain plugins or complex Markdown. The `--no-validate` CLI option or `validate=False` API option can disable this check.
fix
If you are confident the formatting is safe, use `mdformat --no-validate` on the CLI or `mdformat.text(..., validate=False)` in the API. Report the issue if it's a bug in `mdformat` or a plugin.
affects: All versions
gotchaBy default, thematic breaks (horizontal rules) are formatted as a 70-character wide string of underscores. If a different style (e.g., `---`) is desired, a specific plugin like `mdformat-simple-breaks` is required.
fix
Install a plugin like `mdformat-simple-breaks` if you prefer a different style for thematic breaks.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'mdformat'
This error occurs when the 'mdformat' package is not installed in the Python environment.
fix
Install 'mdformat' using pip: 'pip install mdformat'.
ImportError: cannot import name 'text' from 'mdformat'
This error occurs when attempting to import a non-existent 'text' function from the 'mdformat' module.
fix
Ensure you are using the correct import statement: 'from mdformat import text'.
mdformat: command not found
This error occurs when the 'mdformat' command-line tool is not installed or not in the system's PATH.
fix
Install 'mdformat' using pip: 'pip install mdformat', and ensure your PATH includes the directory where pip installs executables.
TypeError: text() missing 1 required positional argument: 'source'
This error occurs when calling the 'text' function without providing the required 'source' argument.
fix
Provide the 'source' argument when calling 'text': 'mdformat.text(source)'.
ValueError: Invalid wrap option: 'invalid_option'
This error occurs when an invalid value is passed to the 'wrap' option in 'mdformat'.
fix
Use a valid 'wrap' option: 'keep', 'no', or an integer (e.g., 80).
Upgrade
Version history
1.0.0latest on PyPI · released Oct 16, 2025
Audit
Dependencies
markdown-it-pyrequiredCore Markdown parser dependency.
mdformat-gfmoptionalOptional plugin to add GitHub Flavored Markdown support.
mdformat-pyprojectoptionalOptional plugin to enable configuration via pyproject.toml.
mdformat-blackoptionalOptional plugin to format Python code blocks using Black.
Agent activity
3 hits · last 30 days
node
2
Resources
mdformat — pip install mdformat · libregistry