Pypandoc is a thin Python wrapper around Pandoc, the universal document converter. It enables Python developers to programmatically convert documents between numerous formats including HTML, Markdown, LaTeX, PDF, DOCX, EPUB, and many others without needing to directly invoke Pandoc from the command line.
The project offers two installation packages: the standard "pypandoc" package which requires an existing Pandoc installation, and "pypandoc_binary" which bundles Pandoc directly for out-of-the-box functionality. Installation is available through pip, conda-forge, or manual setup. The wrapper intelligently detects and uses the highest version of Pandoc available on the system, whether installed separately or included with pypandoc_binary. For users on unsupported platforms or those preferring manual installation, the README provides detailed instructions for installing Pandoc across Windows, Mac OS X, Linux, FreeBSD, and other systems using various package managers.
The core functionality revolves around two primary conversion methods: convert_text for string-based input and convert_file for file-based input. Both methods support specifying input and output formats, passing extra arguments to Pandoc, and writing output directly to files. The wrapper handles multiple input files, supports pathlib objects, and enables the use of Pandoc filters through a straightforward list-based interface. Users can access Pandoc's extensive formatting options through the extra_args parameter, with special handling for custom formatting via the -V parameter.
A notable feature is integrated PDF and LaTeX support through integration with PyTinyTeX, a lightweight LaTeX distribution. When converting to PDF or LaTeX formats, pypandoc automatically manages the LaTeX environment, adding TinyTeX to the system PATH and intelligently installing missing LaTeX packages on demand through up to three retry attempts. This eliminates the need for manual LaTeX configuration, making PDF generation accessible to users without LaTeX expertise.
The project includes a command-line interface accessible via python -m pypandoc or the pypandoc command when installed through pip, extending its utility beyond programmatic use. Logging is implemented using Python's standard logging library, allowing developers to customize message handling before calling pypandoc functions. Utility functions are provided to check available Pandoc versions and identify which Pandoc binary pypandoc is using.
The project participates in Hacktoberfest, as indicated by relevant topic tags and issue labels tracked by GitGenius.
Special note is made that citeproc functionality requires pandoc-citeproc installation, though this is included in prebuilt wheels and conda packages.
