Pdfium Core Bindings Setup

pdfium-core-bindings-setup

What this skill covers

pdfium-render does NOT build or bundle PDFium. It is a Rust wrapper that binds to a separately compiled PDFium library at run time. Binding is the first operation in every pdfium-render program: it produces a Box<dyn PdfiumLibraryBindings>, which Pdfium::new wraps into the Pdfium root handle. If binding fails, nothing else in the crate works.

This skill covers choosing a binding strategy, wiring the Cargo feature flags, sourcing prebuilt PDFium binaries, placing the library file correctly per platform, and the 0.8.x to 0.9.x setup traps. For the ownership tree and the late-binding rationale see pdfium-core-architecture. For diagnosing a binding that fails at run time see pdfium-errors-binding.

Quick reference

Three binding functions exist on the Pdfium struct. ALL are associated functions (no self), and ALL return Result<Box<dyn PdfiumLibraryBindings>, PdfiumError>:

Two path helpers build platform-correct names:

• Pdfium::pdfium_platform_library_name() -> OsString returns the bare file name for the current platform (libpdfium.so, pdfium.dll, libpdfium.dylib).
• Pdfium::pdfium_platform_library_name_at_path(path) -> PathBuf joins that name onto a directory.

Pdfium::new(bindings) wraps a Box<dyn PdfiumLibraryBindings> into a Pdfium.

Decision tree: which binding strategy

Need WASM / browser target?
  YES -> dynamic binding; bundle a separate WASM PDFium module
         (use the paulocoutinhox build). See pdfium-impl-wasm.
  NO  -> Need a single self-contained executable, no sidecar files?
           YES -> static linking (`static` feature + PDFIUM_STATIC_LIB_PATH)
           NO  -> Is PDFium already installed system-wide on every target?
                    YES -> bind_to_system_library()
                    NO  -> dynamic binding with fallback (DEFAULT, simplest)

ALWAYS default to dynamic binding with fallback unless a requirement above forces another path. It is the pattern every official example uses.

Minimal Cargo.toml

[dependencies]
pdfium-render = "0.9"
image = "0.25"

The default features are pdfium_latest, image_latest, and thread_safe. pdfium_latest resolves to a specific PDFium API version (pdfium_7763 as of 0.9.1). See "The critical pinning rule" below.

Pattern: dynamic binding with fallback (default choice)

This is the canonical pattern from the pdfium-render README and examples/export.rs. It tries a library next to the executable first, then falls back to a system-installed PDFium:

use pdfium_render::prelude::*;

let bindings = Pdfium::bind_to_library(
    Pdfium::pdfium_platform_library_name_at_path("./"),
)
.or_else(|_| Pdfium::bind_to_system_library())?;

let pdfium = Pdfium::new(bindings);

Pdfium::default() implements exactly this fallback (extended in 0.8.12 to also try the current working directory). For the common case, write:

let pdfium = Pdfium::default();

ALWAYS bind PDFium once and reuse the Pdfium instance. NEVER re-bind per request: re-loading the library on every call is slow (anti-pattern, issue #59). For long-lived servers, store the bound Pdfium in a once_cell / OnceLock; see pdfium-impl-performance.

The or_else fallback is the ONE sanctioned fallback in this skill, because each arm is a distinct, documented binding strategy and the failure is reported explicitly as a PdfiumError. Do NOT wrap binding in a silent match that swallows the error: a failed bind must surface.

Pattern: system library only

When PDFium is guaranteed installed system-wide (a controlled server image, a Linux distro package), bind directly:

use pdfium_render::prelude::*;

let pdfium = Pdfium::new(Pdfium::bind_to_system_library()?);

bind_to_system_library() searches the OS dynamic-library path. On Linux that is LD_LIBRARY_PATH and the standard ld.so directories; on Windows the PATH and the executable directory; on macOS the DYLD_* paths.

Pattern: static linking

Static linking produces a single self-contained executable with no sidecar .so / .dll / .dylib. It requires the static crate feature:

pdfium-render = { version = "0.9", features = ["static"] }

use pdfium_render::prelude::*;

let pdfium = Pdfium::new(Pdfium::bind_to_statically_linked_library()?);

At build time, set PDFIUM_STATIC_LIB_PATH to the directory containing libpdfium.a (pdfium.lib on Windows). The crate build.rs then emits cargo:rustc-link-lib=static=pdfium and cargo:rustc-link-search=native=$PDFIUM_STATIC_LIB_PATH.

Static builds also need a C++ standard library and, on macOS, CoreGraphics:

• Linux / GNU toolchain: add the libstdc++ feature.
• LLVM toolchain: add the libc++ feature.
• macOS: add the core_graphics feature to resolve _CGBitmap / _CGContext.

NEVER omit the C++ runtime feature on a static build: the link step fails with a wall of undefined references (issue #51). See references/anti-patterns.md.

Feature flags

The PDFium API-version pins and the compile-time gates were introduced in 0.8.24 and 0.8.25; the image_* selectors in 0.8.26. The full pin list and introduction versions are in references/methods.md.

The critical pinning rule

The pdfium_* feature selects which PDFium API version the crate calls. ALWAYS make this feature match the Chromium build number of the actual PDFium binary you bind to. A mismatch produces missing-symbol errors or run-time crashes, NOT a compile error.

To pin explicitly and disable thread safety for single-threaded throughput:

pdfium-render = { version = "0.9", default-features = false, features = [
    "pdfium_7763", "image_025", "image",
] }

bblanchon/pdfium-binaries releases are tagged chromium/<number> (for example chromium/7763). Match the number to the pdfium_<number> feature.

Per-platform library file names

The dynamic loader expects EXACTLY these names. A wrong name produces PdfiumError::LoadLibraryError:

For dynamic binding, the simplest deployment places the platform library in the same directory as the compiled executable and binds with pdfium_platform_library_name_at_path("./"). ALWAYS use the path helpers rather than hardcoding a file name: they pick the correct name per platform.

Build environment variables

ALWAYS point these variables at the directory, NEVER at the file itself. For the per-target form, replace the hyphens in the target triple with underscores, for example PDFIUM_STATIC_LIB_PATH_aarch64_apple_darwin.

Obtaining PDFium binaries

pdfium-render never builds PDFium. Source a prebuilt binary:

• https://github.com/bblanchon/pdfium-binaries/releases: native builds for Android, iOS, Linux (glibc and musl), macOS, Windows, plus an experimental WASM build. Archives are named pdfium-<platform>-<arch>.tgz (for example pdfium-linux-x64.tgz). Releases are tagged chromium/<number>.
• https://github.com/paulocoutinhox/pdfium-lib/releases: Android, iOS, macOS, and WASM builds. ALWAYS use this source for WASM: its WASM build uses a growable heap, while the bblanchon WASM build has a non-growable heap and runs out of memory on multi-page documents.

Version traps: 0.8.x to 0.9.x

The 0.9.0 release also marks all raw FPDF_* functions unsafe and implements Send / Sync; those affect pdfium-core-raw-ffi and pdfium-core-memory, not binding setup itself.

Common failures (quick triage)

Full root-cause analysis lives in pdfium-errors-binding.

Reference files

• references/methods.md: complete signatures for the binding functions, path helpers, Pdfium::new / new_with_config / default, and the full feature flag list with introduction versions.
• references/examples.md: working, verified Rust setup code for dynamic, system, and static binding, plus a OnceLock reuse example.
• references/anti-patterns.md: real binding failures from the GitHub issue tracker, why each fails, and the fix.

Companion skills

• pdfium-core-architecture: the ownership tree and why late binding exists.
• pdfium-errors-binding: diagnosing a binding that fails at run time.
• pdfium-impl-wasm: binding and running PDFium in the browser.
• pdfium-core-raw-ffi: reaching the raw PdfiumLibraryBindings trait.
• pdfium-impl-performance: the bind-once OnceLock pattern for servers.