PDF Color Replacer

Replace specific colors in PDF pages by converting pages to images, performing color replacement, and saving back to a new PDF.

This repository provides:

• An importable API (src/pdf_color_replacer/replacer.py)
• A command-line interface (src/pdf_color_replacer/cli.py)
• Example usage and instructions for installing dependencies

Important: This tool rasterizes pages (converts to images). The output PDF will contain images (not vector text), so file size and text searchability will change. Use only on files you have permission to modify.

Requirements

• Python 3.8+
• Poppler binaries (pdftoppm) available on your PATH
• Python packages: Pillow, pdf2image

Install Python packages:

pip install -r requirements.txt

Install Poppler:

• macOS: brew install poppler
• Debian/Ubuntu: sudo apt install poppler-utils
• Windows:
  • Recommended: choco install -y poppler (requires Chocolatey)
  • Or download binaries from https://github.com/oschwartz10612/poppler-windows/releases, extract and add the bin (or Library/bin) folder to PATH.

Verify Poppler:

pdftoppm -h
pdftocairo -h

CLI Usage

Example: replace a list of target colors with white:

python -m src.pdf_color_replacer.cli \
  input.pdf output.pdf \
  --targets '#efd0d9,#fdfafb,#aaedd4' \
  --replacements '#ffffff' \
  --tolerance 25 \
  --dpi 200 \
  -v

Importing in Python

from pdf_color_replacer.replacer import process_pdf_pages

process_pdf_pages(
    pdf_path="input.pdf",
    output_pdf_path="output.pdf",
    target_hex_list=["#efd0d9", "#fdfafb"],
    new_hex_list_or_single="#ffffff",
    tolerance=25,
    dpi=200,
)