pdf-mint

A local command-line toolkit for PDF files: page inspection, splitting, extraction, deletion, reordering, rotation, merging PDFs with JPG/PNG images, and size optimization. Everything runs on your machine; no file is uploaded anywhere.

Installation

Requires Python 3.10 or newer.

python -m pip install pdf-mint

Commands

Every command accepts --json and then prints a single JSON result object to stdout; progress and errors go to stderr.

Inspect

pdf-mint capabilities --json
pdf-mint info INPUT.pdf --json

capabilities lists the supported operations and compression profiles. info reports the page count and detects encryption, digital signatures, interactive forms, or damage.

Page operations

pdf-mint split INPUT.pdf --each-page --output-dir OUTPUT_DIR --json
pdf-mint split INPUT.pdf --every 5 --output-dir OUTPUT_DIR --json
pdf-mint split INPUT.pdf --groups "1-3;4-8" --output-dir OUTPUT_DIR --json
pdf-mint extract INPUT.pdf --pages "3,1-2" --output OUTPUT.pdf --json
pdf-mint delete INPUT.pdf --pages "2,5" --output OUTPUT.pdf --json
pdf-mint organize INPUT.pdf --order "3,1-2" --rotate "1-2:90;3:180" --output OUTPUT.pdf --json

split writes one PDF per group plus a ZIP archive; add --no-zip to skip the archive, or --profile/--target-size to compress every output.

Merge

pdf-mint merge A.pdf PHOTO.jpg B.pdf --pages "1=3,1-2" --output OUTPUT.pdf --json

Merge accepts any mix of PDF and JPG/PNG files in the given order. --pages INDEX=SELECTION selects pages for a 1-based input position (PDF inputs only); repeat the option for additional inputs. Optional --profile and --target-size compress the result.

Compress

pdf-mint compress INPUT.pdf --profile lossless --output OUTPUT.pdf --json
pdf-mint compress INPUT.pdf --profile balanced --target-size 5MB --output OUTPUT.pdf --json

Profiles: lossless (deduplicate objects and compress streams only), high, balanced (default), and small, which re-encode embedded JPEG images at decreasing quality and resolution caps. With --target-size, the JSON result reports whether the target was met.

Batch task

pdf-mint run-job TASK.json --json

Executes a versioned JSON task file:

{
  "schema_version": "1.0",
  "operation": "merge",
  "inputs": [
    {"path": "A.pdf", "pages": "3,1-2"},
    {"path": "photo.png", "pages": null}
  ],
  "output": "result.pdf",
  "options": {"compression_profile": "balanced", "target_size": "5MB"}
}

Conventions

• Page numbers are 1-based. Selections keep the written order, ranges include both ends, and duplicate pages are rejected.
• Output files never overwrite the input or an existing file.
• MB means 1,000,000 bytes; MiB means 1,048,576 bytes.
• Compression cannot guarantee an arbitrary target size. Check target_met and the warnings in the JSON result instead of assuming success from the file's existence.

Exit codes