# pdfjuicer

[![License](https://img.shields.io/github/license/dmikhr/pdfjuicer.svg)](LICENSE)
![GitHub Release](https://img.shields.io/github/v/release/dmikhr/pdfjuicer)
[![Made with Go](https://img.shields.io/badge/Made%20with-Go-1f425f.svg)](https://go.dev/)
[![Go Reference](https://pkg.go.dev/badge/github.com/dmikhr/pdfjuicer.svg)](https://pkg.go.dev/github.com/dmikhr/pdfjuicer)

🏆 Listed in **[Awesome CLI Apps](https://github.com/agarrharr/awesome-cli-apps?tab=readme-ov-file)** - A curated list of command line apps

🚀  Featured in [Awesome Command Line (CLI/TUI) Programs](https://github.com/toolleeo/awesome-cli-apps-in-a-csv?tab=readme-ov-file#office-tools) catalog

![demo](assets/pdfjuicer_action.png)

A fast and flexible command-line tool for extracting pages from PDF documents as high-quality images. This utility allows you to quickly convert PDF content into various image formats with extensive customization options.

✅ Extract specific pages or page ranges

✅ Control output image format and quality

✅ Scale images to desired dimensions

✅ Generate thumbnails for quick previews and web use

✅ Asynchronous processing for faster extraction

Built with Go, app leverages the speed of a compiled language and concurrent processing via goroutines.

📺 **[Watch video demo on Asciinema](https://asciinema.org/a/hv5p8Qs4KJxY3MOIz6BskBRqA)**

## About

Pdfjuicer was designed with content creators and educators in mind, providing easy ways to extract visual content from PDF documents for presentations, course materials, and digital content creation.

Whether you're creating educational materials, preparing digital content, or need to quickly extract visuals from documentation, **Pdfjuicer** provides a straightforward command-line interface to transform your PDFs into usable image assets.

## Table of Contents
- [Example use cases](#example-use-cases)
- [Commands](#commands)
- [Installation](#installation)
    - [Build from source](#build-from-source)
    - [Adding app to PATH](#adding-app-to-path)
- [Usage examples](#usage-examples)

## Example use cases

### Content Creation for Digital Platforms

- **Social Media** - Transform PDF visuals into shareable graphics
- **E-learning platforms** - Convert PDF content into image assets for online courses
- **Infographic creation** - Pull charts and diagrams as starting points for custom infographics
- **Telegram Channels** - Create image-based content for Telegram groups and channels
- **Blog illustrations** - Extract relevant images from research papers or reports

The built-in thumbnail generation feature creates perfect preview images for content libraries, ensuring students and followers can quickly identify relevant materials before clicking through to full-size content.

### AI and Automation Integration

- **OCR Processing Pipelines** - Extract PDF pages as images that can be fed directly into text recognition engines for data extraction
- **n8n Workflow Integration** - Seamlessly incorporate into n8n automation workflows with simple command execution nodes
- **Batch Processing Systems** - Schedule regular extraction jobs for new documents in content management systems

The tool's CLI nature enables headless operation in server environments, making it easy to integrate with AI processing pipelines where PDFs need to be converted to image format before analysis, classification, or text extraction.

### Professional Applications

- **Creating presentations** - Extract diagrams and illustrations for presentations
- **Documentation** - Create visual guides from technical manuals
- **Portfolio creation** - Showcase design work originally saved in PDF format

## Commands

Specify source file and output folder

```
-s, --source string    Specify path to source file (pdf)
-o, --output string    Specify output folder path
-x, --postfix string   Postfix for a filename
-p, --prefix string    Prefix for a filename (default "page")
```

Specify particular pages or ranges for extraction

```
-P, --pages string     Use this flag to extract specific pages, 
                       example: 2,3,6-8,10
```

Extracted images settings

```
-C, --scale float      Specify image scaling down factor, 
                       example 5, for example 5 means output image will be 
                       5 times smaller than original image (default 1)
-S, --size string      Specify image size, example 640x480, 
                       if not specified will output default size from document
 -F, --format string    Specify output image format (png/jpg) (default "png")
```

Thumbnails settings

```
 -t, --thumb            enable thumbnails generation
 -c, --tscale float     Specify thumbnails scaling down factor, 
                        for example 5 means thumbnail will be 5 times smaller 
                        than original image (default 10)
 -z, --tsize string     Specify thumbnails size e.g. 64x64
```

Miscellaneous

```
-v, --version          Show version
-q, --quiet            Quiet mode (no progress bar, no colored output)
-w, --workers int      Set number of anynchronous workers (default N*)
```

*Default number of asynchronous workers is set by default to number (N) of logical CPU cores in your computer.

## Installation

Currently 2 options are available:

* For macOS on Apple Silicon (M-series), pre-compiled binary is available in the **Releases** section
* Build from source (Go v1.23+ required)

### Build from source

```bash
# clone repository
git clone https://github.com/dmikhr/pdfjuicer.git

# go to source directory and create directory for binary
cd pdfjuicer && mkdir bin

# Download all dependencies defined in go.mod
go mod download

# build binary
go build -o ./bin/pdfjuicer ./cmd

#run binary
./bin/pdfjuicer
```

### Adding app to PATH

In order to be able to call app from terminal simply by typing its name like in *Usage examples* use installation script `install.sh`.

Put `install.sh` in the directory with app binary `pdfjuicer`

It is recommended first to run `install.sh` with `--dry-run` flag to check if installation script works properly. In this mode you will see all messages that are shown during installation but without actual installation.

```bash
# testing script
bash ./install.sh --dry-run

# actual installation
bash ./install.sh
```

⚠️ **Important!** If you build app from source yourself call installation script with `--dev` flag since compiled binary is saved not in the same directory where `install.sh` is located and `--dev` flag takes care of it.

```bash
# testing script
bash ./install.sh --dev --dry-run

# actual installation
bash ./install.sh --dev
```

After installation you will need to add app to PATH. Check the following article for details: [How to Add a Binary (or Executable, or Program) to Your PATH on macOS, Linux, or Windows](https://zwbetz.com/how-to-add-a-binary-to-your-path-on-macos-linux-windows/)

**tl;dr**: add `export PATH="$PATH:path_to_dir_with_binary"` to shell configuration file depending on your shell (typically .bashrc, .bash_profile, .profile or .zshrc).

## Usage examples

See help by calling app either without parameters

```
pdfjuicer
```

or call app with flag `--help` or `-h`

Extract all pages from pdf document as images using default settings (original image size):

```sh
pdfjuicer -s ./tmp/test.pdf -o ./media/pics
```

Extract in quite mode. No progress bar and output formatting. More convenient if app is called from another program.

```sh
pdfjuicer -s ./tmp/test.pdf -o ./media/pics --quiet
```

Extract pages 1 to 3 from `./tmp/test.pdf` and save images `./media/pics` reduce size by a factor of 5

```sh
pdfjuicer -s ./tmp/test.pdf -o ./media/pics --pages=1-3 --scale=5
```

Extract pages `-P` 2-5 from pdf document as images using default settings with thumbnails `-t` using shorthand flags:

```sh
pdfjuicer -s ./tmp/test.pdf -o ./media/pics -t -P=2-5
```

Extract pages 3,5,7-10,15,20-22 in jpg format with specific image and thumbnails sizes

```sh
pdfjuicer -s ./tmp/test.pdf -o ./media/pics -t --pages=3,5,7-10,15,20-22 --size=512x256 --tsize=128x64 --format=jpg
```