pdftopdfa 0.1.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.

This project was built with Claude Code by Anthropic.

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 -- embeds missing fonts with metrically compatible 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 for scanned PDFs via Tesseract
• 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 -- detects if the PDF is already a valid PDF/A file (skips conversion if so)
2. OCR (optional) -- runs Tesseract via ocrmypdf on scanned 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, Linux, or Windows

Install from PyPI

pip install pdftopdfa

Install from the repository

git clone https://github.com/iredpaul/pdftopdfa.git
cd pdftopdfa
pip install .

Optional: OCR support

pip install ".[ocr]"

OCR requires a Tesseract installation on the system. 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
pdftopdfa -v document.pdf

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

# OCR for scanned PDFs
pdftopdfa --ocr 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
• Font replacement -- fonts without a suitable metrically compatible replacement produce a warning; the resulting file may not be fully compliant
• Platform -- supported on macOS, Linux, and Windows
• Python versions -- tested on Python 3.12, 3.13, and 3.14

Development

pip install -e ".[dev]"

Running Tests

pytest

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

Code Quality

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

Documentation

Additional documentation is available in the docs/ folder:

• Usage Guide (CLI & Python API)
• OCR Usage & Quality Presets
• PDF/A Conformance Actions

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

Optional:

• ocrmypdf -- OCR support (requires Tesseract)
• 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)
• 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.