PDF to Image Command Line Tool

Overview

Render PDF pages as images from your terminal or shell scripts. The pdf2image command sends your input to PDFCrowd's servers and saves the result locally.

Installation

Install the command-line client with pip, or see other installation options.

python -m pip install pdfcrowd-cli

Quick Start

You can run the examples below without account setup. The CLI uses demo credentials unless you have configured your own API credentials. Update the input URLs and filenames as needed.

Commands use POSIX-shell syntax, as in Bash or Zsh, and save results in the current directory.

Convert a URL

Fetch a PDF from its URL and save the result locally:

pdf2image --force-zip \
    --output-format=png \
    --output invoice.zip \
    https://your-server.com/invoice.pdf

Convert a File

Upload an existing invoice.pdf file and save invoice.zip:

pdf2image --force-zip \
    --output-format=png \
    --output invoice.zip \
    invoice.pdf

Configure a Conversion

Choose an Input

Supply one URL or local file. Use - to read bytes from stdin, including input piped from another program. Remote URLs must be reachable from PDFCrowd's servers; upload a local file or send its bytes for input on localhost or a private network. See Conversion Input for the supported forms.

For password-protected PDFs, supply the input document's password with --pdf-password. This password is separate from your PDFCrowd API key. Use --print-page-range to select pages.

Read Bytes from Stdin

Read invoice.pdf through stdin and save invoice.zip:

pdf2image --force-zip \
    --output-format=png \
    --output invoice.zip \
    - < invoice.pdf

Add Conversion Settings

Add options before the input. Command-line options override saved conversion defaults.

pdf2image --force-zip \
    --output-format=png \
    --print-page-range=1,3 \
    --output selected-pages.zip \
    report.pdf

Higher DPI produces larger images and files. PNG is the default image format.

The PDF password unlocks the input document; it is separate from your PDFCrowd API key.

See the command reference for all options and Configuration for saved defaults. For more tasks, browse the CLI examples.

Handle the Result

Choose an Output

A single converted page produces an image; multiple pages produce a ZIP archive containing an image for each page. The quick-start examples use --force-zip to always save a ZIP archive, including for a single page. Extract the archive to access the page images.

PNG is the default. Select another format with --output-format. Match the output filename to the actual result: .zip for an archive, or the selected image extension for a single image.

Add --print-is-zipped-output to report whether the result is a ZIP archive.

The examples save the result with --output PATH. The CLI replaces that file only after successful conversion, preserving an existing file if conversion fails. Diagnostics go to stderr.

Omit --output or use --output - to send the result to stdout for a pipe or shell redirection. pdf2image refuses to send binary output directly to an interactive terminal. Shell redirection opens or truncates its destination before the command runs and can leave an empty or partial file on failure.

Handle Errors

Check the command's exit status before using its output: 0 means success and a nonzero status means failure. In a shell script, $? immediately after the conversion contains its status.

Service errors are written to stderr with the prefix PDFCrowd Error: and include the status code, reason code, message, and documentation link when available. These service codes differ from the command's process exit status. See API status codes for service errors and pdf2image help exit-codes for the process exit-code mapping.

Read Conversion Information

Add --print-page-count to report the conversion's page count, or --print-output-size to report the output size in bytes.

Requested conversion information is printed to stderr, leaving stdout available for the result. See Output for all supported information flags.

Limits and Retries

Request rate and concurrency limits depend on your license. Control how quickly your application submits conversions and how many it runs at once. A 429 response concerns request rate; a 430 response concerns requests already in progress. The maximum upload size is 300 MB.

The CLI automatically retries a request once after an HTTP 502 or 503 response. Use --retry-count to change the count, or set it to 0 to disable automatic retries. Account for these retries when adding retries to a script or job runner.

Troubleshooting

Inspect a Conversion

Enable --debug-log and request --print-debug-log-url. This example saves a ZIP archive containing PNG images as response.body and prints the debug-log URL to stderr:

pdf2image --print-debug-log-url \
    --debug-log \
    --force-zip \
    --output-format=png \
    --output response.body \
    https://your-server.com/invoice.pdf

The debug log contains conversion settings and processing details. You can also find logs in your conversion history. A local or connection failure may occur before a conversion log is available.

Common Problems

For help, contact support with available diagnostics, the version from pdf2image --version, and enough detail to reproduce the problem.