@willh/pdf-to-images

A simple and efficient CLI tool to convert PDF pages into individual PNG images.

Features

• 🚀 Convert each PDF page to a high-quality PNG image
• 📁 Automatic output directory management with auto-numbering
• 🔍 Input validation for file existence and extension
• 📊 Progress tracking during conversion
• 🔊 Verbose mode for detailed logging
• ⚡️ High-quality output (3x scale, ~216 DPI)

Installation

You can use this tool directly with npx without installation:

npx -y @willh/pdf-to-images -i sample.pdf -o output

Or install it globally:

npm install -g @willh/pdf-to-images

Usage

Basic Usage

Convert a PDF file to images in the default output directory:

npx -y @willh/pdf-to-images -i sample.pdf -o output

Options

• -i, --input <path> - (Required) Input PDF file path
• -o, --output <path> - Output directory path (default: output)
  • If the directory exists, it will automatically append a number (e.g., output1, output2, etc.)
• -f, --force - Overwrite existing output directory and files (disables auto-numbering)
• --engine <engine> - Render engine: pdfjs (default) or chrome
  • chrome uses headless Chrome/Edge to render pages, which can better match browser PDF rendering and system font substitution.
• --chrome-path <path> - Chrome/Edge executable path (only for --engine=chrome); can also set CHROME_PATH
• --verbose - Enable verbose logging for detailed output
• -v, --version - Display version number
• -h, --help - Display help information

Examples

Convert with verbose output:

npx -y @willh/pdf-to-images -i document.pdf -o images --verbose

Render using headless Chrome (better system font substitution):

npx -y @willh/pdf-to-images -i document.pdf -o images --engine chrome

Overwrite output files in an existing directory:

npx -y @willh/pdf-to-images -i document.pdf -o images -f

Check version:

npx -y @willh/pdf-to-images -v

Get help:

npx -y @willh/pdf-to-images -h

Output

The tool will:

1. Create the output directory if it doesn't exist
2. Convert each page to a PNG file named as {filename}-{page}.png
   • Page numbers are zero-padded (e.g., 01, 02 for <100 pages, 001, 002 for ≥100 pages)
3. Display progress during conversion

Example output files:

output/
├── sample-01.png
├── sample-02.png
├── sample-03.png
└── ...

Error Handling

The tool validates:

• ✅ Input file exists
• ✅ Input file has .pdf extension
• ✅ Output directory can be created
• ✅ PDF file is valid and readable

If any validation fails, the tool will exit with an error message.

Requirements

• Node.js >= 20.16.0
• CI uses Node.js 20.16.x and 22.x

License

MIT License - Copyright (c) 2025 Will 保哥

Author

Will 保哥

Repository

https://github.com/doggy8088/pdf-to-images

Issues

Report issues at: https://github.com/doggy8088/pdf-to-images/issues