| --- |
| tags: |
| - pdf |
| - document-processing |
| - pdf-manipulation |
| - python |
| - cli |
| - automation |
| language: |
| - en |
| license: mit |
| library_name: pdf-manipulator |
| pipeline_tag: other |
| --- |
| |
| # PDF Manipulator |
|
|
|  |
|  |
|  |
|  |
|  |
|  |
|
|
| A comprehensive, single-file command-line toolkit for all PDF page manipulation operations. Merge, split, remove, rotate, crop, watermark, encrypt, number, reorder, and batch-process PDF files with a clean and intuitive CLI. |
|
|
| **Author:** algorembrant |
|
|
| --- |
|
|
| ## Features |
|
|
| | Feature | Command | Description | |
| |----------------------|------------------|-----------------------------------------------------| |
| | Merge PDFs | `merge` | Combine multiple PDFs into one, or interleave pages | |
| | Split PDF | `split` | Split into individual pages or page ranges | |
| | Remove Pages | `remove` | Remove one or more pages by number or range | |
| | Extract Pages | `extract` | Extract specific pages into a new PDF | |
| | Reorder Pages | `reorder` | Rearrange pages in any custom order | |
| | Rotate Pages | `rotate` | Rotate pages by 90, 180, or 270 degrees | |
| | Reverse Pages | `reverse` | Reverse the page order | |
| | Duplicate Pages | `duplicate` | Duplicate specific pages N times | |
| | Insert Blank Page | `insert-blank` | Insert blank page before or after a position | |
| | Insert PDF Pages | `insert` | Insert pages from another PDF at a position | |
| | Replace Pages | `replace` | Replace pages with pages from another PDF | |
| | Crop Pages | `crop` | Crop pages to a custom bounding box | |
| | Scale / Resize | `scale` | Scale pages by factor or resize to A4/letter | |
| | Watermark | `watermark` | Add text or PDF watermark to all pages | |
| | Stamp / Overlay | `stamp` | Overlay a stamp PDF on pages | |
| | Page Numbers | `number` | Add page numbers at any position | |
| | Encrypt | `encrypt` | Password-protect a PDF | |
| | Decrypt | `decrypt` | Remove password from a PDF | |
| | Metadata | `metadata` | View or edit PDF title, author, subject, keywords | |
| | Bookmarks | `bookmarks` | List or add bookmark/outline entries | |
| | Extract Text | `text` | Extract plain text from pages | |
| | Info / Inspect | `info` | Display page count, dimensions, and metadata | |
| | N-Up Layout | `nup` | Arrange multiple pages per sheet (2x1, 2x2, etc.) | |
| | Compress | `compress` | Losslessly compress PDF streams | |
| | Batch Remove | `batch-remove` | Remove pages from all PDFs in a directory | |
| | Batch Merge | `batch-merge` | Merge all PDFs in a directory into one | |
| | Batch Split | `batch-split` | Split all PDFs in a directory into pages | |
|
|
| --- |
|
|
| ## Requirements |
|
|
| - Python 3.9 or newer |
| - System dependency: **Poppler** (required for `nup` command only) |
|
|
| --- |
|
|
| ## Installation |
|
|
| ### 1. Clone the Repository |
|
|
| ```bash |
| git clone https://github.com/algorembrant/pdf-manipulator.git |
| cd pdf-manipulator |
| ``` |
|
|
| ### 2. Install Python Dependencies |
|
|
| ```bash |
| pip install -r requirements.txt |
| ``` |
|
|
| ### 3. Install Poppler (Required for N-Up Layout) |
|
|
| The `nup` command uses `pdf2image`, which requires Poppler to be installed on your system. |
|
|
| | Platform | Install Command | |
| |--------------|-------------------------------------------------------| |
| | Ubuntu/Debian| `sudo apt-get install -y poppler-utils` | |
| | macOS | `brew install poppler` | |
| | Windows | Download from https://github.com/oschwartz10612/poppler-windows/releases and add `bin/` to your PATH | |
|
|
| If you do not need the `nup` command, Poppler is not required. |
|
|
| --- |
|
|
| ## Usage |
|
|
| ### Page Range Syntax |
|
|
| | Syntax | Meaning | |
| |----------|-------------------------------------| |
| | `3` | Page 3 only | |
| | `1,3,5` | Pages 1, 3, and 5 | |
| | `2-5` | Pages 2 through 5 inclusive | |
| | `1,3-5,7`| Pages 1, 3, 4, 5, and 7 | |
|
|
| Pages are always 1-indexed (first page = 1). |
|
|
| --- |
|
|
| ### Step-by-Step Guide |
|
|
| #### Merge PDFs |
|
|
| ```bash |
| # Merge two or more PDFs in order |
| python pdf_manipulator.py merge -i file1.pdf file2.pdf file3.pdf -o merged.pdf |
| |
| # Interleave pages (page 1 from file1, page 1 from file2, page 2 from file1, ...) |
| python pdf_manipulator.py merge -i file1.pdf file2.pdf -o interleaved.pdf --interleave |
| ``` |
|
|
| #### Split PDF |
|
|
| ```bash |
| # Split into individual pages (saved to a directory) |
| python pdf_manipulator.py split -i input.pdf -o ./split_pages |
| |
| # Extract a range of pages into a single file |
| python pdf_manipulator.py split -i input.pdf -o ./split_pages --range 1-5 |
| python pdf_manipulator.py split -i input.pdf -o ./split_pages --range 2,4,6 |
| ``` |
|
|
| #### Remove Pages |
|
|
| ```bash |
| # Remove page 3 |
| python pdf_manipulator.py remove -i input.pdf -o output.pdf --pages 3 |
| |
| # Remove multiple pages |
| python pdf_manipulator.py remove -i input.pdf -o output.pdf --pages 1,3,5 |
| |
| # Remove a range of pages |
| python pdf_manipulator.py remove -i input.pdf -o output.pdf --pages 2-5 |
| |
| # Remove mixed selection |
| python pdf_manipulator.py remove -i input.pdf -o output.pdf --pages 1,3-5,7 |
| ``` |
|
|
| #### Extract Pages |
|
|
| ```bash |
| # Extract pages 1-3 into a new PDF |
| python pdf_manipulator.py extract -i input.pdf -o output.pdf --pages 1-3 |
| |
| # Extract specific pages |
| python pdf_manipulator.py extract -i input.pdf -o output.pdf --pages 2,4,6 |
| ``` |
|
|
| #### Reorder Pages |
|
|
| ```bash |
| # Place page 3 first, then page 1, then page 2, then page 4 |
| python pdf_manipulator.py reorder -i input.pdf -o output.pdf --order 3,1,2,4 |
| ``` |
|
|
| #### Rotate Pages |
|
|
| ```bash |
| # Rotate all pages 90 degrees clockwise |
| python pdf_manipulator.py rotate -i input.pdf -o output.pdf --angle 90 |
| |
| # Rotate only pages 1 and 3 by 180 degrees |
| python pdf_manipulator.py rotate -i input.pdf -o output.pdf --angle 180 --pages 1,3 |
| |
| # Rotate pages 2-4 by 270 degrees |
| python pdf_manipulator.py rotate -i input.pdf -o output.pdf --angle 270 --pages 2-4 |
| ``` |
|
|
| #### Reverse Page Order |
|
|
| ```bash |
| python pdf_manipulator.py reverse -i input.pdf -o output.pdf |
| ``` |
|
|
| #### Duplicate Pages |
|
|
| ```bash |
| # Duplicate page 2 so it appears 3 times in a row |
| python pdf_manipulator.py duplicate -i input.pdf -o output.pdf --pages 2 --times 3 |
| ``` |
|
|
| #### Insert Blank Pages |
|
|
| ```bash |
| # Insert a blank page after page 2 |
| python pdf_manipulator.py insert-blank -i input.pdf -o output.pdf --after 2 |
| |
| # Insert a blank page before page 1 |
| python pdf_manipulator.py insert-blank -i input.pdf -o output.pdf --before 1 |
| ``` |
|
|
| #### Insert Pages from Another PDF |
|
|
| ```bash |
| # Insert all pages from extra.pdf after page 3 of base.pdf |
| python pdf_manipulator.py insert -i base.pdf --insert-file extra.pdf -o output.pdf --after 3 |
| |
| # Insert before page 2 |
| python pdf_manipulator.py insert -i base.pdf --insert-file extra.pdf -o output.pdf --before 2 |
| ``` |
|
|
| #### Replace Pages |
|
|
| ```bash |
| # Replace page 2 of base.pdf with page 1 of new.pdf |
| python pdf_manipulator.py replace -i base.pdf --replace-file new.pdf -o output.pdf --pages 2 --replace-pages 1 |
| ``` |
|
|
| #### Crop Pages |
|
|
| ```bash |
| # Crop all pages (coordinates in PDF points: left,bottom,right,top) |
| python pdf_manipulator.py crop -i input.pdf -o output.pdf --box "50,50,500,700" |
| |
| # Crop only pages 1-3 |
| python pdf_manipulator.py crop -i input.pdf -o output.pdf --box "50,50,500,700" --pages 1-3 |
| ``` |
|
|
| #### Scale / Resize Pages |
|
|
| ```bash |
| # Scale all pages to 50% of original size |
| python pdf_manipulator.py scale -i input.pdf -o output.pdf --factor 0.5 |
| |
| # Resize all pages to A4 |
| python pdf_manipulator.py scale -i input.pdf -o output.pdf --to-size A4 |
| |
| # Resize to US Letter |
| python pdf_manipulator.py scale -i input.pdf -o output.pdf --to-size letter |
| ``` |
|
|
| #### Add Watermark |
|
|
| ```bash |
| # Add a text watermark with defaults (red diagonal, 15% opacity) |
| python pdf_manipulator.py watermark -i input.pdf -o output.pdf --text "CONFIDENTIAL" |
| |
| # Custom opacity and angle |
| python pdf_manipulator.py watermark -i input.pdf -o output.pdf --text "DRAFT" --opacity 0.3 --angle 45 |
| |
| # Use a PDF file as watermark |
| python pdf_manipulator.py watermark -i input.pdf -o output.pdf --watermark-pdf wm.pdf |
| ``` |
|
|
| #### Stamp / Overlay |
|
|
| ```bash |
| # Overlay stamp.pdf on all pages |
| python pdf_manipulator.py stamp -i input.pdf -o output.pdf --stamp-pdf stamp.pdf |
| |
| # Overlay on page 1 only |
| python pdf_manipulator.py stamp -i input.pdf -o output.pdf --stamp-pdf stamp.pdf --pages 1 |
| ``` |
|
|
| #### Add Page Numbers |
|
|
| ```bash |
| # Add page numbers at bottom center (default) |
| python pdf_manipulator.py number -i input.pdf -o output.pdf |
| |
| # Custom position and starting number |
| python pdf_manipulator.py number -i input.pdf -o output.pdf --position bottom-right --start 1 |
| |
| # Custom format string |
| python pdf_manipulator.py number -i input.pdf -o output.pdf --position top-right --format "Page {n}" |
| ``` |
|
|
| Available positions: `bottom-center`, `bottom-left`, `bottom-right`, `top-center`, `top-left`, `top-right` |
|
|
| #### Encrypt / Decrypt |
|
|
| ```bash |
| # Encrypt with a user password |
| python pdf_manipulator.py encrypt -i input.pdf -o output.pdf --user-pass mypassword |
| |
| # Encrypt with both user and owner password |
| python pdf_manipulator.py encrypt -i input.pdf -o output.pdf --user-pass mypassword --owner-pass ownerpassword |
| |
| # Decrypt / remove password |
| python pdf_manipulator.py decrypt -i encrypted.pdf -o decrypted.pdf --password mypassword |
| ``` |
|
|
| #### Metadata |
|
|
| ```bash |
| # View metadata |
| python pdf_manipulator.py metadata -i input.pdf |
| |
| # Set metadata fields |
| python pdf_manipulator.py metadata -i input.pdf -o output.pdf \ |
| --set-title "Annual Report 2024" \ |
| --set-author "algorembrant" \ |
| --set-subject "Finance" \ |
| --set-keywords "annual,report,finance" |
| ``` |
|
|
| #### Bookmarks / Outline |
|
|
| ```bash |
| # List all bookmarks |
| python pdf_manipulator.py bookmarks -i input.pdf |
| |
| # Add bookmarks |
| python pdf_manipulator.py bookmarks -i input.pdf -o output.pdf \ |
| --add "Introduction:1,Chapter 1:3,Chapter 2:8" |
| ``` |
|
|
| #### Extract Text |
|
|
| ```bash |
| # Print text from all pages |
| python pdf_manipulator.py text -i input.pdf |
| |
| # Extract text from pages 1-3 and save to file |
| python pdf_manipulator.py text -i input.pdf --pages 1-3 -o extracted.txt |
| ``` |
|
|
| #### PDF Info |
|
|
| ```bash |
| python pdf_manipulator.py info -i input.pdf |
| ``` |
|
|
| #### N-Up Layout (Requires Poppler) |
|
|
| ```bash |
| # 2 pages side-by-side on one sheet |
| python pdf_manipulator.py nup -i input.pdf -o output.pdf --layout 2x1 |
| |
| # 4 pages in a 2x2 grid on one sheet |
| python pdf_manipulator.py nup -i input.pdf -o output.pdf --layout 2x2 |
| ``` |
|
|
| #### Compress |
|
|
| ```bash |
| python pdf_manipulator.py compress -i input.pdf -o output.pdf |
| ``` |
|
|
| #### Batch Operations |
|
|
| ```bash |
| # Remove page 1 (e.g. cover page) from all PDFs in a directory |
| python pdf_manipulator.py batch-remove --dir ./pdfs --pages 1 --suffix _no_cover |
| |
| # Merge all PDFs in a directory into one |
| python pdf_manipulator.py batch-merge --dir ./pdfs -o merged_all.pdf |
| |
| # Split all PDFs in a directory into individual pages |
| python pdf_manipulator.py batch-split --dir ./pdfs --out-dir ./split_output |
| ``` |
|
|
| --- |
|
|
| ## Notes |
|
|
| - All page numbers are 1-indexed (first page is page 1). |
| - The `nup` command requires Poppler to be installed on your system. |
| - For encrypted PDFs, use the `--password` flag with any command that reads them (decrypt first, or add password support per command as needed). |
| - Output directories are created automatically if they do not exist. |
|
|
| --- |
|
|
| ## License |
|
|
| MIT License. See [LICENSE](LICENSE) for details. |
|
|
| --- |
|
|
| ## Author |
|
|
| **algorembrant** |
|
|
