PDF Joiner

Python CLI to merge multiple PDFs into a single file, with configurable sorting.

Installation

pip install pdf-joiner

Install from source

git clone https://github.com/mariano-soto/pdf-joiner.git
cd pdf-joiner
pip install .

Install for development

git clone https://github.com/mariano-soto/pdf-joiner.git
cd pdf-joiner
pip install -e ".[dev]"

Quick usage

# Merge individual PDFs
pdfm a.pdf b.pdf c.pdf -o combined.pdf

# Merge all PDFs from a folder
pdfm ./my-documents -o result.pdf

# Merge sorted by modification date (newest first)
pdfm ./documents -o chronological.pdf --sort mtime --reverse

# Merge with natural alphabetical order (doc2.pdf before doc10.pdf)
pdfm ./documents -o alpha.pdf --sort natural

# Use defaults (generates merged.pdf, no sorting)
pdfm a.pdf b.pdf

Options

Sort modes

• none: No sorting (preserves the order files are passed in)
• name: Alphabetical by name (case-insensitive)
• natural: Natural order (file2.pdf before file10.pdf)
• mtime: By modification date (oldest first)
• ctime: By creation date (oldest first)

When a folder is passed as input, the default sort is natural. When individual files are passed, the default sort is none.

Advanced examples

# Combine multiple folders and files
pdfm ./chapters ./images cover.pdf -o book.pdf --sort natural

# Sort by inverse creation date (newest first)
pdfm ./backup -o recent.pdf --sort ctime --reverse

# Merge without modifying input order
pdfm cap1.pdf cap3.pdf cap2.pdf -o manual.pdf --sort none

Requirements

• Python >= 3.10
• pypdf >= 5.0.0
• typer >= 0.12.0

Development

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run tests with coverage
pytest --cov=pdf_joiner --cov-report=term-missing

License

MIT

Author

Mariano Soto — soymarianosoto@proton.me