pdf-pagenum

Center page number annotations in PDF files. Repositions FreeText annotations added by macOS Preview's text function, or adds new page numbers to pages that don't have them.

Features

• Reposition mode: find existing page number annotations and center them at the bottom of each page
• Add mode: create new page numbers on specified pages with --add
• Start offset: begin numbering from any page with --start N
• Smart placement: auto-detects body content boundaries, places page numbers below content with proper margins
• Preserves A4 dimensions: never modifies page size, accepts content overlap on tight pages
• Landscape aware: handles both portrait and landscape orientations correctly
• White background: page numbers have a white fill to stay readable over images

Install

pip install pdf-pagenum

Usage

# Reposition existing page numbers
pdf-pagenum ./input_folder/ ./output_folder/

# Add page numbers to all pages (starting from 1)
pdf-pagenum ./input_folder/ ./output_folder/ --add all

# Add page numbers starting from 5
pdf-pagenum ./input_folder/ ./output_folder/ --add all --start 5

# Add page numbers to pages 3 through 7 only
pdf-pagenum ./input_folder/ ./output_folder/ --add 3-7

# Add page numbers to pages 1, 3, 5, 6, 7
pdf-pagenum ./input_folder/ ./output_folder/ --add 1,3,5-7 --start 10

Requirements

• Python >= 3.9
• PyMuPDF >= 1.23.0
• natsort >= 8.0.0

License

MIT