---
id: panflute
version: "2.3.1"
license: BSD3
license_treatment: permissive
maintenance: aging
---

# panflute — Pythonic Pandoc filters

License: permissive · Maintenance: aging · Downloads: 169.7K/mo

## What it is and what it does

Panflute is a Python wrapper around Pandoc's document processing pipeline that lets you write filters by manipulating document elements as Python objects rather than working directly with JSON. It depends on click for CLI handling and pyyaml for configuration, and requires a matching Pandoc binary installed on your system to function.

You write a filter function that receives document elements (paragraphs, text, code blocks, etc.) and returns transformed versions of them. Panflute handles the marshalling between Pandoc's JSON representation and Python objects, so you work with readable class instances instead of raw data structures. This is most useful when you need to customize how Pandoc converts between formats—for example, rewriting links, injecting metadata, or applying domain-specific transformations to code blocks.

Use it for:

- Rewrite internal document links or citations during Markdown-to-HTML conversion for a static site generator.
- Transform code blocks with custom syntax into formatted output (e.g., mermaid diagrams to SVG).
- Inject metadata or styling directives into LaTeX output for academic papers written in Markdown.
- Strip or modify elements (images, scripts, comments) when converting documents for different audiences.
- Automate document preprocessing for research workflows that combine Markdown, Pandoc, and custom logic.

## Worth the install?

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

Panflute provides a Pythonic interface for writing Pandoc filters, allowing you to programmatically transform documents between markup formats by manipulating their abstract syntax trees.

Yes, if you need to programmatically transform documents via Pandoc and want to avoid writing raw JSON filters. Install friction is low and the license is permissive. Be aware that the package has not been released in 877 days; check that your Pandoc version (2.11.0.4–3.1.x for version 2.3.1) is compatible before committing to it for production workflows.

## Install

pip install panflute
uv add panflute
poetry add panflute

## Installing panflute

Before you install: Low friction installation with only two runtime dependencies (click and pyyaml). The package is in production/stable status but has not been released for 877 days; the repository remains active with recent commits, though maintenance appears infrequent.

License in practice: BSD3 license is permissive and poses no restrictions on commercial or private use, modification, or redistribution as long as the license text is included.

Quickstart:

pip install panflute

import panflute as pf

def action(elem, doc):
    if isinstance(elem, pf.Str):
        return pf.Str(elem.text.upper())

if __name__ == '__main__':
    pf.run_filter(action)

Requires a compatible Pandoc installation on the system; panflute 2.3.1 supports Pandoc 2.11.0.4–3.1.x and Pandoc API versions 1.22–1.23.

Verify before relying:

- Whether the 877-day gap since last release indicates active maintenance or dormancy relative to Pandoc's release cycle.
- Performance characteristics when processing large documents or complex filter chains.
- Compatibility with PyPy in practice, given the classifier indicates support but no runtime evidence is provided.

## Package facts

- License: BSD3 (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: aging
- Downloads: 169.7K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

pandoc filter library python, document transformation markdown, ast manipulation pandoc, markdown to latex conversion, pandoc plugin framework, document-processing, pandoc-integration, markup-transformation

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