pdf-pagenum: Fix Messy macOS Preview Page Numbers in PDFs from the CLI

A pip-installable CLI tool that auto-centers off-center page number annotations created by macOS Preview, or batch-adds new ones — with smart content avoidance and landscape support. The Problem If you've ever used macOS Preview to add page numbers to a PDF (via the text annotation tool), you know the pain: numbers land wherever you drop them, never centered, and manually positioning dozens or hundreds of them is soul-crushing. Especially when the PDF has mixed portrait and landscape pages. I ran into this preparing a thesis — 200+ pages of final manuscript, page numbers visibly off-center on every single page. Editing each one by hand wasn't an option. The Solution pdf-pagenum is a single CLI command that reads a folder of PDFs and centers every page number annotation to the bottom of its page. It works by: Detecting FreeText annotations that look like page numbers Measuring body content boundaries on each page Repositioning the annotation to a clean, centered position below the content — with proper margins Preserving the original page dimensions (no resizing, ever) If your PDF has pages with no annotations at all, it can generate new page numbers from scratch in the correct position. Install pip install pdf-pagenum That's it. PyMuPDF and natsort come along as dependencies. Usage Fix Mode (default) Reposition existing page number annotations so they're centered at the bottom: pdf-pagenum ./scans/ ./output/ This is the mode you'll use 90% of the time — it takes whatever rough page numbers Preview gave you and snaps them to the mathematically correct center. Add Mode Generate brand-new page numbers on pages that lack them: # Number all pages starting from 1 pdf-pagenum ./scans/ ./output/ --add all # Number pages 3 through 7 only pdf-pagenum ./scans/ ./output/ --add 3-7 # Number specific pages, starting count from 10 pdf-pagenum ./scans/ ./output/ --add 1,3,5-7 --start 10 Ranges and comma-separated lists can be mixed freely. Start Offset The --start N flag works in b