A tool to merge odd and even pages from separate PDF files into a single document. This is particularly useful when scanning double-sided documents using a single-sided scanner.
MergePDF provides multiple ways to merge your PDF files:
- Command-line interface with user-friendly progress indicators
- REST API for programmatic access and integration
- macOS Finder integration via Automator Quick Action
- Merge odd pages (1,3,5...) from one PDF with even pages (2,4,6...) from another
- Handle reversed even pages from single-sided scanners
- Visual progress indicators and native macOS notifications
- Simple API for integration with other tools
- Finder context menu integration
-
Download the latest release:
curl -L https://github.com/yannrapaport/mergepdf/archive/refs/heads/main.zip -o mergepdf.zip unzip mergepdf.zip cd mergepdf-main
-
Make the CLI script executable:
chmod +x merge_pdfs_cli.sh
-
Set up the background service:
# Create the service configuration cp com.yannrapaport.mergepdf-api.plist ~/Library/LaunchAgents/ # Edit paths in the configuration to match your installation # (replace USERNAME with your macOS username) sed -i '' "s|/Users/yannrapaport|/Users/$USER|g" ~/Library/LaunchAgents/com.yannrapaport.mergepdf-api.plist # Start the service launchctl load ~/Library/LaunchAgents/com.yannrapaport.mergepdf-api.plist
-
Verify installation:
curl http://localhost:8000/api/health
You should see
{"status":"ok"}
The merge_pdfs_cli.sh
script provides a user-friendly interface with progress indicators and descriptive feedback:
./merge_pdfs_cli.sh [OPTIONS] ODD_PDF EVEN_PDF
-o, --output FILE
: Specify output filename (default: merged_TIMESTAMP.pdf)-d, --dir DIR
: Specify output directory (default: ~/Downloads)-q, --quiet
: Disable progress indicators-h, --help
: Display help message
# Basic usage
./merge_pdfs_cli.sh odd_pages.pdf even_pages.pdf
# Specify output file and location
./merge_pdfs_cli.sh -o merged_document.pdf -d ~/Desktop odd_pages.pdf even_pages.pdf
For programmatic access, MergePDF provides a REST API that can be accessed locally.
python -m uvicorn api:app --host 127.0.0.1 --port 8000
POST /api/merge
: Upload and merge two PDF filesGET /api/download/{job_id}
: Download the merged PDFGET /api/health
: Check API health status
# Upload files to merge
JOB_ID=$(curl -s -X POST "http://localhost:8000/api/merge" \
-F "odd_file=@odd_pages.pdf" \
-F "even_file=@even_pages.pdf" \
-F "output_filename=merged.pdf" | grep -o '"job_id":"[^"]*' | cut -d'"' -f4)
# Download the merged file
curl -o merged.pdf "http://localhost:8000/api/download/$JOB_ID"
The PDF merging service runs in the background and starts automatically when you log in.
# Check if service is running
curl http://localhost:8000/api/health
# Restart the service
launchctl unload ~/Library/LaunchAgents/com.yannrapaport.mergepdf-api.plist
launchctl load ~/Library/LaunchAgents/com.yannrapaport.mergepdf-api.plist
# Stop the service
launchctl unload ~/Library/LaunchAgents/com.yannrapaport.mergepdf-api.plist
# View service logs
cat /path/to/mergepdf/logs/api_*.log
MergePDF can be integrated into the macOS Finder context menu using Automator. This allows you to right-click on two PDF files and merge them directly.
For detailed setup instructions, see README_AUTOMATOR.md.
- macOS 10.14 Mojave or newer
- bash shell
- curl (for API testing)
If you want to modify or contribute to the project:
-
Clone the repository:
git clone https://github.com/yannrapaport/mergepdf.git cd mergepdf
-
Create and activate a virtual environment:
python3 -m venv venv source venv/bin/activate
-
Install dependencies:
pip install PyPDF2 fastapi uvicorn python-multipart
- Python 3.6+
- PyPDF2 (PDF manipulation)
- FastAPI (API framework)
- Uvicorn (ASGI server)
- python-multipart (file upload handling)
- bash (for CLI script)
This project is open source and available under the MIT License.