Install & Compatibility
Where this runs
tested against v1.3.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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.156s · 20MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.7s · import 0.144s · 21MB
18MB installed
● package 18MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
load
✓ from frontmatter import load
loads
✓ from frontmatter import loads
dumps
✓ from frontmatter import dumps
Post
✓ from frontmatter import Post
Frontmatter
✓ from frontmatter import Frontmatter
✗ from frontmatter import frontmatter
The class is capitalized; direct `frontmatter` usually refers to the module, not an instance.
YAMLHandler
✓ from frontmatter.handlers import YAMLHandler
Required if explicitly specifying the YAML handler, otherwise it's the default for `load`/`loads`.
JSONHandler
✓ from frontmatter.handlers import JSONHandler
Required to parse JSON frontmatter explicitly.
TOMLHandler
✓ from frontmatter.handlers import TOMLHandler
Required to parse TOML frontmatter explicitly.
This quickstart demonstrates how to load content with YAML frontmatter from a string, access its metadata and content, modify them, and dump the post back into a string. It also shows how to explicitly use a `JSONHandler` for different frontmatter formats.
import frontmatter
# Example content with YAML frontmatter
content_string = '''---
title: My Awesome Post
author: John Doe
tags:
- python
- frontmatter
---
This is the *body* of my post.
It can contain anything.
'''
# Load from a string
post = frontmatter.loads(content_string)
print(f"Title: {post['title']}")
print(f"Author: {post.metadata.get('author')}")
print(f"Content:\n{post.content}")
# Modify the post
post['status'] = 'published'
post.metadata['tags'].append('documentation')
post.content = "New content! " + post.content
# Dump back to a string
modified_content = frontmatter.dumps(post)
print("\n--- Modified Content ---\n")
print(modified_content)
# Example using JSON handler
json_content_string = '''---
{\"title\": \"JSON Post\", \"lang\": \"en\"}
---
Body of JSON post.
'''
json_post = frontmatter.loads(json_content_string, handler=frontmatter.handlers.JSONHandler)
print(f"\nJSON Post Title: {json_post['title']}")
frontmatter --version
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'frontmatter'
The `frontmatter` package is not installed in the current Python environment or is not accessible.
fixRun `pip install frontmatter` to install the library.
FileNotFoundError: [Errno 2] No such file or directory: 'your_file_name.md'
The file path provided to `frontmatter.load()` does not correspond to an existing file.
fixVerify the file path is correct, the file exists at that location, and your program has appropriate read permissions.
AttributeError: 'Post' object has no attribute 'data'
The `Post` object stores frontmatter metadata in its `metadata` dictionary attribute, not directly in an attribute named `data`.
fixAccess the metadata using `post.metadata` (e.g., `post.metadata['title']` or `post.metadata.get('key', default_value)`). YAMLError: while parsing a block mapping
The YAML frontmatter block in the input string or file is malformed (e.g., incorrect indentation or syntax), preventing PyYAML from parsing it.
fixCorrect the syntax of the YAML frontmatter block, ensuring proper indentation, valid key-value pairs, and correct YAML structure.
Upgrade
Version history
1.3.0latest on PyPI · released May 20, 2026
Audit
Dependencies
PyYAMLrequiredUsed for parsing and dumping YAML frontmatter, which is the default handler.