pdfium_dart

Dart FFI bindings for the PDFium library. This package provides low-level access to PDFium's C API from Dart.

This package is part of the pdfrx project.

Requirements

  • Dart 3.13 or later

Overview

This package contains auto-generated FFI bindings for PDFium using ffigen. It is designed to be a minimal, pure Dart package that other packages can depend on to access PDFium functionality.

Key Features:

  • Pure Dart package with no Flutter dependencies
  • Auto-generated FFI bindings using ffigen
  • Provides direct access to PDFium's C API
  • Downloads and bundles PDFium at build time using Dart native assets
  • Includes getPdfium() for resolving PDFium across Dart and Flutter runtimes
  • Supports Windows, Linux, Android, and macOS build hooks

Usage

Basic Usage

This package is primarily intended to be used as a dependency by higher-level packages like pdfium_flutter and pdfrx_engine. Direct usage is possible but not recommended unless you need low-level PDFium access.

import 'package:pdfium_dart/pdfium_dart.dart';
import 'dart:ffi';

// If you already have PDFium loaded
final pdfium = PDFium(DynamicLibrary.open('/path/to/libpdfium.so'));

PDFium Loading

The getPdfium function resolves the PDFium library for the current runtime. You can also pass an explicit module path for custom deployments or tests:

import 'package:pdfium_dart/pdfium_dart.dart';

void main() async {
  // Resolves PDFium for the current Dart or Flutter runtime.
  final pdfium = getPdfium();

  // Or load a specific shared library.
  final customPdfium = getPdfium(modulePath: '/path/to/libpdfium.so');

  // Use PDFium API
  // ...
}

The build hook downloads binaries from bblanchon/pdfium-binaries and exposes them through Dart native assets. At runtime, getPdfium() chooses the appropriate loading strategy:

  • modulePath is used first when explicitly provided.
  • Flutter apps on iOS/macOS use the PDFium XCFramework that is already linked into the app by pdfium_flutter.
  • Native PDFium assets are not built for iOS; Flutter iOS apps should depend on pdfium_flutter so the XCFramework is linked by the Flutter plugin.
  • Pure Dart commands on macOS, such as dart test, dart run, and dart compile, use the libpdfium.dylib native asset.
  • Flutter apps on Linux look for libpdfium.so in the shared library directory relative to the resolved executable.
  • Other supported platforms first try the platform library name, then fall back to the bundled native asset recorded in .dart_tool/native_assets.yaml.

Download proxies

The build hook honors the standard http_proxy, https_proxy, and no_proxy environment variables when it downloads PDFium. On Windows, when no proxy environment variable is defined for the requested scheme, it also uses the current user's enabled static WinINet proxy configuration. An explicit environment proxy takes precedence over the Windows system proxy. Transient connection failures and HTTP 408, 429, and 5xx responses are retried with short backoff delays.

Generating Bindings

Prerequisites

The ffigen process requires LLVM/Clang to be installed for parsing C headers:

  • macOS: Install via Homebrew

    brew install llvm

  • Linux: Install via package manager

    # Ubuntu/Debian
sudo apt-get install libclang-dev

# Fedora
sudo dnf install clang-devel

  • Windows: Download and install LLVM from llvm.org

Regenerating Bindings

To regenerate the FFI bindings:

  1. Run the ffigen helper:

    dart tool/ffigen.dart

    The helper downloads PDFium headers into .dart_tool/pdfium_headers/ before running ffigen.

    Use dart tool/ffigen.dart --force to refresh the downloaded headers, or dart tool/ffigen.dart --download-only to only prepare the headers.

The bindings are generated from PDFium headers using the ffigen configuration in pubspec.yaml.

Platform Support

Platform Architecture Support
Windows x64, ARM64, x86 ✅
Linux x64, ARM64, ARM, x86 ✅
Android ARM64, ARMv7, x86, x86_64 ✅
macOS x64, ARM64 ✅
HarmonyOS (OHOS) ARM64 ✅ (bring your own libpdfium.so)

Note: For Flutter applications, use pdfium_flutter unless you specifically need the lower-level Dart bindings directly. pdfium_flutter includes the Flutter deployment layer for all native platforms except Web.

HarmonyOS note: the build hook does not download PDFium for OHOS targets. Bundle a libpdfium.so under the HAP's libs/<abi>/ directory; the loader resolves it via a bare-name dlopen from the app's native library directory at runtime.

Libraries

pdfium_dart
Dart FFI bindings for PDFium library.