Install & Compatibility
Where this runs
tested against v2.4 · 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.248s · 21.5MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.7s · import 0.240s · 22MB
19MB installed
● package 19MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
pandoc
✓ import pandoc
Main module for reading, writing, and manipulating Pandoc documents.
types
✓ from pandoc.types import Str, Space, Para, Meta
Provides access to the Abstract Syntax Tree (AST) types for fine-grained document manipulation.
This quickstart demonstrates how to read a Markdown string into a Pandoc document object, access and modify its Abstract Syntax Tree (AST) using `pandoc.types`, and then write the modified document back to a Markdown string. This showcases the core functionality for programmatic document manipulation.
import pandoc
from pandoc.types import Str, Space, Para, Meta
# Read a simple markdown string into a Pandoc document object
text = "Hello world!"
doc = pandoc.read(text)
print(f"Initial document: {doc}")
# Access and modify an element in the document's Abstract Syntax Tree (AST)
# For "Hello world!", doc is Pandoc(Meta({}), [Para([Str('Hello'), Space(), Str('world!')])])
# The paragraph is at doc[1][0]
# The 'world!' string is at doc[1][0][2][0]
paragraph = doc[1][0]
# Modify the 'world!' string to 'Python!'
# The Str object is at paragraph[2] (0: Str('Hello'), 1: Space(), 2: Str('world!'))
# The actual string value is the first element of the Str tuple: Str('world!')[0]
paragraph[2][0] = 'Python!'
# Write the modified document back to a markdown string
modified_text = pandoc.write(doc)
print(f"Modified document text: {modified_text.strip()}")
# Example of converting to a different format (requires actual pandoc executable)
# doc_to_convert = pandoc.read("# My Title\n\nHello from Pandoc!", format='markdown')
# html_output = pandoc.write(doc_to_convert, format='html')
# print(f"HTML output:\n{html_output}")
pandoc --version
Debug
Known issues
breakingThe Python `pandoc` library is a thin wrapper and does not bundle the Pandoc executable. Users MUST install the Pandoc command-line tool separately (e.g., via `conda install pandoc`, `sudo apt install pandoc`, or `brew install pandoc`). Failure to do so will result in runtime errors as the Python library will not find the `pandoc` binary.fixEnsure the Pandoc executable is installed on your system and accessible in the system's PATH before using the Python `pandoc` library.
affects: All versions
gotchaThe `pandoc` Python library should not be confused with `pypandoc`. While both are Python wrappers for Pandoc, `pypandoc` offers a `pypandoc_binary` package that bundles the Pandoc executable, whereas `pandoc` (this library) always requires a separate installation of the underlying Pandoc tool.
gotchaWhen programmatically interacting with the Pandoc executable (e.g., via Python's `subprocess` module or the `pandoc` library's underlying calls), command-line arguments, especially those with values, must be passed as distinct items in a list. Combining them into a single string (e.g., `'-Vtitle="My Title"'`) can lead to incorrect parsing by Pandoc. Instead, use `['-V', 'title="My Title"']`.fixAlways pass command-line arguments as separate list items to ensure correct parsing by the Pandoc executable. Utilize `shlex.split()` for robust conversion of command strings to lists if needed.
affects: All versions when passing options to Pandoc
breakingThe underlying Pandoc executable (version 3.1 and later) changed how it parses code block attributes. The syntax ````{lang}` (without a leading dot) is no longer interpreted as a language class but as a literal string. The correct syntax for specifying a language class is ````{.lang}````. This change in the Pandoc executable can affect how the Python `pandoc` library processes markdown documents.fixUpdate Markdown documents to use ````{.lang}```` for code block language attributes when targeting Pandoc executable versions 3.1 or newer. If processing older documents, be aware of potential parsing differences. affects: Pandoc executable versions >= 3.1
gotchaThe Python `pandoc` library is tested against specific versions of the Pandoc executable. While it might issue a warning for unsupported Pandoc executable versions instead of failing, using an incompatible version could lead to unexpected behavior or incorrect document transformations due to differences in the underlying document model.fixRefer to the Python `pandoc` library's documentation or changelog for the Pandoc executable versions it is officially tested against and supports. Ensure your installed Pandoc executable matches a supported version range.
affects: All versions (when Pandoc executable version mismatch occurs)
Upgrade
Version history
2.4latest on PyPI · released Aug 7, 2024
Audit
Dependencies
pandoc (executable)requiredThe Python 'pandoc' library is a wrapper around the external Pandoc command-line tool, which must be installed separately and accessible in the system's PATH.
plumbumrequiredRequired for process execution and shell interaction.
plyrequiredRequired for parsing.