Install & Compatibility
Where this runs
tested against v1.5.1 · 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.022s · 17.8MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.5s · import 0.018s · 18MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
toJSONFilter
✓ from pandocfilters import toJSONFilter
This is the primary function for creating a standalone filter script that reads from stdin and writes to stdout.
walk
✓ from pandocfilters import walk
Used for applying an action function to every object in a parsed Pandoc AST.
Str, Para, Header, Emph
✓ from pandocfilters import Str, Para, Header, Emph
Common AST element constructors for manipulating the document structure.
This quickstart demonstrates a simple Pandoc filter that converts all regular string elements ('Str') in the document's Abstract Syntax Tree (AST) to uppercase. Save this code as a Python file (e.g., `caps_filter.py`), make it executable, and then run Pandoc with the `--filter` option pointing to your script.
#!/usr/bin/env python
"""
Pandoc filter to convert all regular text ('Str' elements) to uppercase.
Run with: pandoc input.md --filter ./caps_filter.py -o output.html
"""
from pandocfilters import toJSONFilter, Str
def caps(key, value, format, meta):
if key == 'Str':
return Str(value.upper())
if __name__ == "__main__":
toJSONFilter(caps)
Debug
Known issues
breakingPython 2 support was officially dropped after `pandocfilters` version 1.5.0. If you are on Python 2, you must use `pandocfilters` <= 1.5.0.fixUpgrade to Python 3 or pin `pandocfilters` to version 1.5.0 or earlier.
affects: >=1.5.1
breakingCompatibility with the underlying `pandoc` executable is critical and can break filters due to AST changes. Specific `pandocfilters` versions are tied to `pandoc` versions.fixUse `pandocfilters` <= 1.2.4 for `pandoc` versions 1.12-1.15. Use `pandocfilters` >= 1.3.0 for `pandoc` versions >= 1.16. `pandocfilters` 1.4.0 introduced compatibility with `pandoc` 1.17.3's new JSON format. Always check the `pandocfilters` README for the latest compatibility matrix.
affects: <1.4.0
gotchaThe `get_filename4code` utility (used for generating filenames for code blocks, e.g., for images) by default creates temporary directories that are NOT automatically cleaned up. This can lead to an accumulation of files if not managed.fixSet the environment variable `PANDOCFILTER_CLEANUP` to any non-empty value (e.g., '1') before running your filter. This will cause temporary directories to be created in a temporary location and automatically removed upon filter exit.
affects: All versions with `get_filename4code`
gotchaStarting from version 1.5.0, the `examples/` directory is no longer included in the PyPI distribution (source or binary wheels). It is only available in the source repository on GitHub.fixIf you rely on the examples, clone the GitHub repository (`http://github.com/jgm/pandocfilters`) directly instead of installing from PyPI, or browse the examples on GitHub.
affects: >=1.5.0
gotchaPandoc itself offers built-in Lua filters (since Pandoc 2.0) which do not require external language interpreters (like Python) and may offer better performance for some use cases. An alternative Python library, `panflute`, also exists, offering a more 'Pythonic' API.fixConsider if a Lua filter (using Pandoc's `--lua-filter` option) or `panflute` might be a better fit for your specific filtering needs, especially for new projects.
affects: All versions
breaking`pandocfilters` expects valid JSON input from `pandoc` (typically via stdin). If `pandoc` does not output valid JSON, or outputs nothing, `pandocfilters` will fail with a `JSONDecodeError`.fixEnsure that `pandoc` is correctly configured to output JSON to the filter's stdin. This often means running `pandoc` with the `--to json` or `-t json` option and piping its output to the Python script, or calling the Python script directly as a filter where `pandoc` manages the I/O.
affects: All versions
breakingThe `pandocfilters` library expects a JSON representation of the Pandoc AST on `sys.stdin`. A `json.decoder.JSONDecodeError` at line 1, column 1 (char 0) indicates that no valid JSON was provided to the filter, often because the filter was run directly without `pandoc`, `pandoc` failed to execute, or `pandoc` produced non-JSON output (e.g., an error message) to `stdout`.fixEnsure your Python script is executed by `pandoc` using the `--filter` option (e.g., `pandoc input.md --filter ./your_filter.py -o output.html`), verify that `pandoc` is installed and accessible in your environment's PATH, and check `pandoc`'s output for errors if run standalone.
affects: All versions
Errors
Common errors & fixes
ImportError: No module named pandocfilters
The Python interpreter cannot find the 'pandocfilters' package, usually because it's not installed, or the environment where Pandoc is run doesn't have access to the installed package.
fixEnsure pandocfilters is installed for the correct Python interpreter using `pip install pandocfilters` or `pip3 install pandocfilters`. If using a virtual environment, activate it before installing and running Pandoc.
Error running filter /path/to/your_filter.py: Could not find executable /path/to/your_filter.py
Pandoc was unable to locate or execute the specified Python filter script. This can happen if the path is incorrect, the script lacks executable permissions, or the shebang (`#!/usr/bin/env python3`) is wrong or missing.
fixVerify the filter script's path is correct relative to where Pandoc is called, ensure the script has executable permissions (`chmod +x your_filter.py`), and confirm the shebang points to a valid Python interpreter (e.g., `#!/usr/bin/env python3`).
Error running filter ...: Error in $: Failed reading: not a valid json value.
The Python filter produced output that is not a valid JSON representation of Pandoc's Abstract Syntax Tree (AST), which Pandoc expects from filters. This often occurs due to malformed output or printing debug information to standard output.
fixInspect the Python filter for syntax errors, ensure that all debug prints go to `sys.stderr` instead of `sys.stdout`, and that the filter consistently returns valid Pandoc AST objects (or `None` for no change, or a list of objects for replacement).
TypeError: 'str' object is not subscriptable
This error frequently arises in `pandocfilters` when a filter function attempts to access a string value as if it were a list or dictionary (e.g., `value[0]`), typically when processing a `Str` element where `value` is just the string content, not a structured list.
fixCarefully check the structure of the `value` argument for each `key` type your filter handles. For 'Str' elements, `value` is a plain string. Access its content directly or use string methods. For other types (like 'Para', 'Header'), `value` is typically a list or tuple, and its internal structure (e.g., `value[0]`, `value[1]['c']`) needs to be matched to the Pandoc AST specification for that element type.
Upgrade
Version history
1.5.1latest on PyPI · released Jan 18, 2024
Audit
Dependencies
pythonrequiredRequires Python versions >=2.7 and not 3.0-3.3. Python 2 support was dropped after 1.5.0.
pandocrequiredFilters interact with the pandoc document converter; a compatible pandoc installation (>= 1.12 recommended) is required at the system level.