PDF Watermark / Stamp Tool

Simple Python utility to stamp an image (logo/badge/watermark) onto pages of a PDF using Pillow and PyMuPDF. Supports positioning, opacity, size as a fraction of page width, page selection, margins, and downsampling for small output files.

Features

• Stamp on all pages or specific 0-based page indices
• Anchors: top-left, top-right, bottom-left, bottom-right, center
• Size by page width via width_frac (0–1)
• Margin in points (1 pt = 1/72")
• Opacity baked into PNG alpha (works on older PyMuPDF)
• Downsample with effective_dpi to keep PDFs small

Requirements

• Python 3.10+
• Dependencies: Pillow, PyMuPDF
  • For CLI: Typer, Rich

Install

cd pdf_watermark_tool
python -m venv .venv
source .venv/bin/activate  # macOS/Linux
# .venv\\Scripts\\activate  # Windows PowerShell
pip install -r requirements.txt

Install with pipx (recommended)

# macOS (Homebrew)
brew install pipx
pipx ensurepath

# Install from this local folder
pipx install /path/to/pdf_watermark_tool

Run the CLI:

stamp-pdf --help
stamp-pdf in.pdf logo.png out.pdf -p "1,3,5,10-12" -w 0.16 -a top-left -m 24 -o 0.7

Upgrade or uninstall:

pipx upgrade pdf-watermark-tool
pipx uninstall pdf-watermark-tool

• Command installed: stamp-pdf (from pyproject.toml [project.scripts]).

Usage (Python API)

from stamp_pdf import stamp_image_on_pdf

stamp_image_on_pdf(
    input_pdf="input.pdf",
    image_path="watermark.png",
    output_pdf="output.pdf",
)

Advanced options

from stamp_pdf import stamp_image_on_pdf

stamp_image_on_pdf(
    input_pdf="input.pdf",
    image_path="badge.png",
    output_pdf="output.pdf",
    page_indices=[0, 2, 5],         # only pages 1, 3, 6 (0-based)
    width_frac=0.20,                # fraction of page width
    anchor="bottom-right",         # 'top-left'|'top-right'|'bottom-left'|'bottom-right'|'center'
    margin_pt=24.0,                 # points
    opacity=0.65,                   # 0–1
    effective_dpi=120               # 96–150 is a good range
)

CLI Usage

python stamp_pdf.py input.pdf watermark.png output.pdf \
  --pages "1-3,7" \
  --width-frac 0.18 \
  --anchor top-right \
  --margin 18 \
  --opacity 0.6 \
  --dpi 120

Examples

• All pages, bottom-right (default), 20% width

python stamp_pdf.py in.pdf logo.png out.pdf

• Specific pages 1,3,5 and a range 10-12 (1-based)

python stamp_pdf.py in.pdf badge.png out.pdf -p "1,3,5,10-12" -w 0.16 -a top-left -m 24 -o 0.7

• Center placement, higher DPI for sharpness

python stamp_pdf.py in.pdf mark.png out.pdf -a center -w 0.25 --dpi 150

Tips

• Prefer PNG with transparency for best results.
• Lower effective_dpi reduces output size; raise it for crisper stamps.
• page_indices is optional. Omit or set to None to stamp all pages.

Troubleshooting

• If installing PyMuPDF fails, upgrade build tooling then retry:

python -m pip install --upgrade pip setuptools wheel
pip install pymupdf