pdftopdfa 0.6.0

Convert PDF files to the archival PDF/A format

pdftopdfa

I built pdftopdfa as a free and open-source alternative to Ghostscript-based PDF/A converters. Ghostscript uses a dual license (AGPL/commercial) that makes it difficult to use in commercial products without purchasing a license. pdftopdfa is licensed under the permissive MPL-2.0 and can be freely used in commercial projects. Instead of re-rendering via Ghostscript, it modifies the PDF structure directly using pikepdf (based on QPDF), preserving the original content, fonts, and layout.

Highlights

• No Ghostscript required -- direct PDF manipulation via pikepdf/QPDF
• PDF/A-2b, 2u, 3b, 3u -- supports modern PDF/A levels (ISO 19005-2 and 19005-3)
• Automatic font embedding -- uses policy-approved Windows system fonts or bundled replacements
• Font subsetting -- reduces file size by removing unused glyphs
• CJK support -- embeds Noto Sans CJK for Chinese, Japanese, and Korean text
• ICC color profiles -- automatically embeds sRGB, CMYK, and grayscale profiles
• Batch processing -- converts entire directories, optionally recursive
• Integrated validation -- checks conformance via veraPDF
• OCR support -- optional text recognition via Tesseract with offline PaddleOCR page orientation
• Simple API -- usable as CLI tool or Python library

How It Works

pdftopdfa applies a multi-step conversion pipeline to make a PDF compliant with the PDF/A standard:

1. Pre-check -- skips encrypted and digitally signed PDFs, then detects if the PDF is already a valid PDF/A file (skips conversion if the existing level meets or exceeds the target; optionally skips any veraPDF-compliant PDF/A via --skip-any-pdfa; see Usage Guide for details)
2. OCR (optional) -- uses the bundled PaddleOCR model to orient every page in best mode, then runs Tesseract via ocrmypdf on pages without a text layer
3. Font compliance -- analyzes all fonts, embeds missing ones, adds ToUnicode mappings, subsets embedded fonts, and fixes encoding issues
4. Sanitization -- removes or fixes non-compliant elements (JavaScript, non-standard actions, transparency groups, annotations, optional content, etc.)
5. Metadata -- synchronizes XMP metadata with the document info dictionary and sets the PDF/A conformance level
6. Color profiles -- detects color spaces and embeds the required ICC profiles (sRGB, CMYK/FOGRA39, sGray)
7. Save -- writes the output with the correct PDF version header

Installation

Prerequisites

• Python 3.12, 3.13, or 3.14
• macOS 14 or later on Apple Silicon, Linux, or Windows

Intel-based Macs are not supported. Installation on macOS requires the ARM64 wheels provided by ONNX Runtime for Apple Silicon.

pip install pdftopdfa

Optional: OCR support

pip install "pdftopdfa[ocr]"

OCR requires a Tesseract installation on the system. The best preset uses a bundled PaddleOCR ONNX model and never downloads model files at runtime. See docs/ocr.md for details on OCR usage and quality presets.

Quick Start

# Simple conversion (creates document_pdfa.pdf)
pdftopdfa document.pdf

# Specific PDF/A level
pdftopdfa -l 2b document.pdf

# With validation (note: -v = --validate, not verbose; use --verbose for logs)
pdftopdfa -v document.pdf

# Skip any existing veraPDF-compliant PDF/A
pdftopdfa --skip-any-pdfa document.pdf

# Explicitly convert a signed PDF, invalidating its digital signatures
pdftopdfa --allow-signature-invalidation document.pdf

# Convert an entire directory
pdftopdfa -r ./documents/ ./output/

# OCR for scanned PDFs
pdftopdfa --ocr document.pdf

# Preserve known proprietary stamps as PDF Stamp annotations
pdftopdfa --preserve-stamps document.pdf

from pathlib import Path
from pdftopdfa import convert_to_pdfa

result = convert_to_pdfa(
    input_path=Path("input.pdf"),
    output_path=Path("output.pdf"),
    level="2b",
)

See docs/usage.md for the full CLI reference, Python API documentation, and examples.

Limitations

• No PDF/A-1 support -- only PDF/A-2 and PDF/A-3 levels are supported
• Encrypted PDFs -- password-protected PDFs cannot be converted
• Digitally signed PDFs -- signed PDFs are copied unchanged by default because conversion would invalidate their signatures; use --allow-signature-invalidation only when an unsigned archival copy is intentional
• Font replacement -- fonts without a suitable metrically compatible replacement produce a warning; the resulting file may not be fully compliant
• Non-embedded CIDFonts (Identity encoding) -- content streams reference glyph IDs of the original font; after replacement with a substitute font the same glyph IDs point to different or missing glyphs, so the affected text may render incorrectly or invisibly. Text extraction and copy/paste stay correct because the original ToUnicode mapping is preserved. A warning is emitted for each replaced CIDFont

Font Sourcing

• On Windows, pdftopdfa may automatically embed a conservative fixed allowlist of local fonts from %WINDIR%\Fonts.
• A Windows system font is only used when the installed file lives under %WINDIR%\Fonts, its actual PostScript name is allowlisted, and its OpenType fsType permits outline embedding.
• On macOS and Linux, system fonts are never auto-embedded; bundled replacement fonts are used instead.
• fsType checks are a technical safeguard only and do not replace the font vendor's EULA or other license terms.
• For auditable deployments, keep the allowlist tied to reviewed target systems or golden images.

Development

pip install -e ".[dev]"

Running Tests

pytest

The test suite contains 2600+ tests covering fonts, color profiles, metadata, sanitization, and end-to-end conversion.

Code Quality

ruff check src/ tests/   # Linting
ruff format src/ tests/  # Formatting

Documentation

Additional documentation is available in the docs/ folder:

• Usage Guide (CLI & Python API)
• OCR Guide
• PDF/A-2/3 rules reference (veraPDF)

Contributing

Contributions are welcome! Please open an issue to report bugs or suggest features, or submit a pull request.

Dependencies

Core:

• pikepdf -- PDF manipulation (based on QPDF)
• lxml -- XMP metadata processing
• fonttools -- Font analysis, subsetting, and embedding
• click -- CLI framework
• colorama -- Colored terminal output
• tqdm -- Progress bars
• PaddleOCR -- document orientation classification
• ONNX Runtime -- CPU inference for the bundled orientation model

Optional:

• ocrmypdf -- OCR support (requires Tesseract)
• pypdfium2 -- PDF page rasterizer for OCR
• veraPDF -- ISO-compliant PDF/A validation

Acknowledgments

This project bundles the following resources:

• Liberation Fonts -- metrically compatible replacements for the PDF Standard 14 fonts (SIL OFL 1.1)
• PP-LCNet_x1_0_doc_ori -- bundled document-orientation model (Apache-2.0)
• Noto Sans CJK -- CJK font coverage (SIL OFL 1.1)
• Noto Sans Symbols 2 -- symbol font replacement (SIL OFL 1.1)
• STIX Two Math -- math font replacement (SIL OFL 1.1)
• sRGB2014.icc -- ICC sRGB profile (ICC)
• ISOcoated_v2_300_bas.icc -- ICC CMYK profile, FOGRA39 (zlib/libpng license)
• sGray -- compact grayscale ICC profile (CC0-1.0)
• Adobe cmap-resources -- CID-to-Unicode mapping data (BSD 3-Clause)

License

This project is licensed under the Mozilla Public License 2.0 or later (MPL-2.0+) -- see LICENSE for details.