PoDoFo: a C++17 library for parsing, editing and signing PDF files

An object model for the PDF format, not a text extraction tool

PoDoFo is a free portable C++ library to work with the PDF file format. It provides classes to parse a PDF file and modify its content, allowing to write it back to disk easily, and it also provides facilities to create your own PDF files from scratch.

That framing matters. PoDoFo is not a command line tool that turns a PDF into text, and it is not a renderer. It is the layer underneath an application that has to treat a PDF as a structured document: pages, objects, content streams, annotations, form fields, fonts, signatures.

The feature list is what tells you how far it goes. PDF parsing with high-level entity inspection covers annotations, form fields and others. PDF writing with support for incremental updates means a signature can be added to an existing file without rewriting the whole document, which is the mechanism digital signing depends on. PDF signing comes with PAdES-B compliance, RSA and ECDSA encryption, and asynchronous or deferred signing.

The text side is where the detail is. Text drawing comes with automatic CID encoding generation and font subsetting, which are the two things that make a C++ PDF writer usable for anything beyond Latin-1 text, and there is full-featured low-level Unicode text extraction alongside advanced CJK language support covering both extraction and automatic multi-byte encoding.

Then there is the compliance work: PDF/A compliance preservation, for example font embedding and simultaneous PDF/A and PDF/UA compliance, and PDF/UA compliance preservation, for example when adding annotations or form fields. Deferred font file data embedding rounds it out.

The primary language is C++17, the licence file at the root is a custom one GitHub cannot classify, and the homepage documentation is at podofo.github.io/podofo/documentation. The last push was on 2026-10-17, with releases 1.1.2 from 2026-08-19, 1.1.1 from 2026-06-08 and 1.1.0 from 2026-05-01.

No rendering and no text shaping, stated plainly

The README puts the limitations in two sentences, and they are the two facts a buyer most needs.

PoDoFo does not support rendering PDF content yet. Text writing is also limited as it currently does not perform proper text shaping/kerning.

Rendering absent means no rasteriser, no page-to-image conversion and no preview. If your application needs to show a page, you need a different library for that, or you build it out of the primitives PoDoFo gives you.

Text shaping absent is subtler and bites in a specific place. Without shaping and kerning, a ligature-heavy script or a language with complex contextual rules will not render correctly, and even Latin text with kerning pairs will look slightly off. The CJK support in the feature list is about encoding, that is getting the right multi-byte encoding generated and extracted, not about laying out complex scripts.

The word yet in the rendering sentence is doing some work, and the project has an active release line: 1.1.0, 1.1.1 and 1.1.2 landed within about four months of each other in 2026. So rendering is a gap that is being worked on rather than a permanent decision. Whether that matters to you depends on your timeline rather than on the architecture.

The other structural boundary is the API surface itself, and the repository says so with a dedicated document. There is an API-MIGRATION.md at the root, alongside CODING-STYLE.md, SOURCE-LAYOUT.md and a TODO.md. PoDoFo has had a long history of internal API churn, and a project that documents its migration path between versions is telling you the API has changed before and will again.

Dependencies, minimum versions and the toolchain floor

To build PoDoFo you need a C++17 compiler, CMake 3.23 and a set of libraries with tentative minimum versions.

The required ones are freetype2 at 2.11, fontconfig at 2.13.94 which is required for Unix platforms and optional for Windows, OpenSSL where 1.1 and 3.0 are supported, LibXml2 at 2.9.12 and zlib. The optional ones are libjpeg at 9d, libtiff at 4.0.10 and libpng at 1.6.37.

That list is the shape of the project. FreeType and fontconfig are there for font handling, OpenSSL for the signing and encryption work, LibXml2 for the XML metadata that PDF carries and for XMP, and zlib for the stream compression that every PDF uses.

The compiler floor is stated separately and is worth reading before you pick a build environment: msvc++ 14.16 which is Visual Studio 2017 15.9, gcc 9.0, clang/llvm 9.0, and XCode 11.0. The versions it is regularly tested with are newer: Visual Studio 2022 17.14, gcc 9.3.1, XCode 15.4 and NDK r28.

That gap between minimum and tested is a real signal. The minimums are what the code compiles against, and the tested list is what the CI actually exercises, so if you are on something older than the tested set you are on your own.

The NDK entry is also worth noticing, because it connects to the cross-compilation warning elsewhere in the README. PoDoFo is known to be working in cross-compilation toolchains such as Android and iOS development, but support may not be provided in such scenarios. The warning continues that if you decide to manually build dependencies you are assumed to know how to identify possible library clashes and mismatches and how to deal with compilation and linking problems. So mobile is a supported-enough path to try and an unsupported-enough path to depend on.

The continuous integration runs in Ubuntu Linux, MacOS and Windows, bootstrapping the CMake project, building and testing the library.

Four package managers, and the playground for reproducing bugs

PoDoFo is known to compile through a multitude of package managers, including APT, brew, vcpkg and Conan, and the README recommends using one of them.

The APT route installs the dependencies and then configures a debug build.

sudo apt install -y libfontconfig1-dev libfreetype-dev libxml2-dev libssl-dev libjpeg-dev libpng-dev libtiff-dev
mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Debug ..
cmake --build . --config Debug

The brew route has to pass extra hints because Homebrew's prefix layout does not always match what CMake looks for.

brew install fontconfig freetype openssl libxml2 jpeg-turbo libpng libtiff cmake
mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Debug -DCMAKE_FIND_FRAMEWORK=NEVER -DCMAKE_PREFIX_PATH=`brew --prefix` -DFontconfig_INCLUDE_DIR=`brew --prefix fontconfig`/include -DOPENSSL_ROOT_DIR=`brew --prefix openssl@3` ..
cmake --build . --config Debug

Conan is the shortest, because Conan supplies the dependencies and CMake just has to find them.

mkdir build
cd build
conan install ..
cmake -DCMAKE_BUILD_TYPE=Debug ..
cmake --build . --config Debug

And vcpkg passes its toolchain file to CMake directly.

vcpkg install
mkdir build
cmake "-DCMAKE_TOOLCHAIN_FILE=vcpkg.cmake" -DCMAKE_BUILD_TYPE=Debug -B build
cmake --build build --config Debug

For Windows, the vcpkg quickstart is worth the detour, and setting the environment variable VCPKG_DEFAULT_TRIPLET to x64-windows defaults to 64-bit dependencies, with VCPKG_ROOT pointing at the repository.

There is also a playground directory in the repository with pre-built dependencies for popular architectures and operating systems. The README calls it the recommended setting to develop the library and reproduce bugs, while not recommended for deploying an application that uses PoDoFo. That is a useful distinction: it is a developer convenience, not a packaging strategy.

Since version 1.0, PoDoFo has a fairly advanced CMake integration and can be consumed as a CMake package, so once it is integrated in your package manager you can locate it and compile against it.

LGPL or MPL for the library, GPL for the tools

The licensing is two-tiered and it is easy to misread, so it is worth stating precisely.

The PoDoFo library is licensed under the LGPL 2.0 or later terms or, at your option, MPL 2.0. The PoDoFo tools are licensed under the GPL 2.0 or later terms.

So the library, the part you link into your application, is available under either of two weak copyleft licences, and you choose. The command line utilities in the tools/ directory are under GPL, which matters only if you redistribute those binaries.

The LGPL option is the classic one for a library like this: dynamic linking against the LGPL library leaves your own code under your own terms, and the LGPL conditions then attach to the library itself. The MPL option is file-level copyleft, which is often easier to reason about for a codebase of mixed ownership because the copyleft obligation stops at the file boundary.

There is a third party component caveat and it is specific enough to matter. The NOTICE file covers the use of third party components, and the README advises considering disabling the AFDKO integration if you plan to distribute the PoDoFo library with GPL 2.0-only projects. AFDKO is the Adobe font development kit, and shipping it inside an LGPL library that ends up in a GPL-2.0-only product creates a licence incompatibility. The escape hatch is a build option, which is a reasonable engineering answer, but it is a decision you have to make deliberately rather than discover later.

The repository carries COPYING.LGPL and COPYING.MPL at the root, alongside NOTICE and SECURITY.md, so the actual terms are there to read. The custom licence classification in the repository metadata does not match the README's description, which is the sort of discrepancy a compliance scan will flag and a human has to resolve.

Where PoDoFo is the wrong tool

The first wrong-tool case is anything that needs pages rendered. If your requirement is thumbnails, previews, page images or anything that turns a PDF into a picture, PoDoFo is not the library, because rendering is not supported. Tools built on other PDF stacks exist for that, and combining one for rendering with PoDoFo for structure is a normal architecture rather than a workaround.

The second case is a text quality requirement. Without shaping and kerning, text you draw will not look the way a designer expects, and it will be wrong for scripts that need contextual shaping. If the output is a text-heavy document that has to look professionally typeset, that is a different kind of library.

The third case is a team that needs a stable API without reading migration notes. The repository ships API-MIGRATION.md, which is a document about change between versions, and it also ships a TODO.md. Combined with a 1.x version line that has produced three releases in four months, that tells you the API surface is still moving and you should budget for a port when you upgrade.

The fourth case is a mobile deployment that depends on PoDoFo's own support. The README is explicit that cross-compilation toolchains are known to work but support may not be provided, and it puts the burden of resolving library clashes and linking problems on whoever builds the dependencies manually. If your target is Android or iOS and you are not prepared to own the dependency stack, that is a significant risk to carry.

There is a practical note for contributors and for anyone reading the tree. The layout is unusually well documented for a C++ project: SOURCE-LAYOUT.md describes the source organisation, CODING-STYLE.md the conventions, and there are AGENTS.md and CLAUDE.md files at the root for tooling. The examples/ directory contains helloworld and helloworld-base14 projects, which is where you should start, and the staging/ directory at the root suggests the code is organised in layers. The test/ directory and man/ directory are present too, so the project does carry its own test and documentation infrastructure.

Editorial conclusion

PoDoFo suits a C++ team that has to read, modify or sign PDFs inside a larger application, since it gives you an object model for the format rather than a text extraction tool, and it ships as a CMake package consumable through APT, vcpkg, Conan or brew. It does not suit a project that needs pages rendered to images or text shaped properly, because rendering is not supported and text writing has no shaping or kerning. Before adopting, check the LICENSE choices against your distribution model, since the library is LGPL 2.0 or later or MPL 2.0 while the command line tools are GPL 2.0 or later, and read the API-MIGRATION.md file in the repository root before porting from an older PoDoFo.

Frequently asked questions

Official sources

1. Issues
2. podofo/podofo on GitHub
3. Project website
4. README
5. Releases