PDF to Image Command line Reference

Conversion from PDF to image.

pdf2image [options] SOURCE
pdfcrowd pdf2image [options] SOURCE
pdf2image auth ACTION
pdf2image help [TOPIC|OPTION|CATEGORY]

Commands and Options

Conversion Input

SOURCE

Supply exactly one input source:

  • URL: an HTTP(S) URL.
  • File: the path to an existing local input file.
  • Standard input: - reads input bytes from a pipe or redirection.

Options may appear before or between sources. Use -- before a file name that starts with a dash.

Examples:
  • URL: pdf2image --force-zip --output result.zip https://example.com/input.pdf
  • Local file: pdf2image --force-zip --output result.zip input.pdf
  • Standard input: pdf2image --force-zip --output result.zip - < input.pdf

Output

Results go to standard output by default. Binary output requires a file, pipe, or redirection; only pdf2text writes directly to a terminal. Some converters produce ZIP archives containing their results. Diagnostics use standard error.

--output, -o FILE

Save the result to FILE. Use - for standard output.

An existing output file is replaced only after a successful conversion.

To send binary results to standard output, redirect them to a file or pipe them to another program.

Default:
standard output
Example:
  • pdf2image --output FILE SOURCE

--print-page-count

Print page count to stderr after conversion.

Configuration

If the default configuration file exists, conversions read it automatically. Conversions never save settings automatically. Run pdf2image help configuration to see the default file path. --config and --no-config are mutually exclusive.

Use a UTF-8 INI file with option-name = value lines and no [section] headings. Use the option names with hyphens and without leading dashes, for example debug-log instead of --debug-log. Lines starting with # or ; are comments.

Inline values can span multiple lines when each continuation line is indented more than the setting name. A blank line ends the value. Use a separate file for content that needs blank lines or exact formatting.

--config PATH

Read conversion defaults from PATH instead of the default file.

Command-line options override the settings in this file. This option applies to conversion settings; credentials are stored separately.

Examples:
  • pdf2image --config PATH --output FILE SOURCE
  • pdf2image --config ./defaults.ini -o result SOURCE

--no-config

Ignore saved conversion defaults for this command.

Command-line conversion options still apply. Saved credentials and environment variables still apply. The config file is left unchanged.

Example:
  • pdf2image --no-config --output FILE SOURCE

--init-config

Create a commented config file that you can edit.

Open the created file and remove the leading # from settings you want to use. Future conversions read the default file automatically.

Use --config PATH to create a file at another location. An existing file is left unchanged. This command does not perform a conversion.

Examples:
  • pdf2image --init-config [--config PATH]
  • pdf2image --init-config
  • pdf2image --init-config --config ./defaults.ini

--show-config

Show saved defaults and command-line overrides without converting.

Each setting shows whether it came from the config file or the command line. Other options use their API defaults.

Sensitive values and inline HTML, CSS, and JavaScript are hidden. No files are changed.

Examples:
  • pdf2image --show-config [options]
  • pdf2image --show-config
  • pdf2image --no-config --show-config

Authentication

For account setup and credential selection, see Authentication.

auth ACTION

Manage credentials shared by all converter commands.

ACTION: Choose login, status, or logout.

Usage:
pdf2image auth ACTION
pdfcrowd auth ACTION

auth login [--non-interactive]

Save your PDFCrowd username and API key for all converter commands.

Use both credential environment variables when set; otherwise prompt in an interactive terminal. The API-key prompt hides your input.

In a script, use --non-interactive to require environment credentials without prompting. This saves the account; it does not perform a conversion.

Usage:
pdf2image auth login [--non-interactive]
pdfcrowd auth login [--non-interactive]
auth login --non-interactive

This option applies only to auth login.

Require environment credentials when saving an account with auth login; never prompt.

Set both PDFCROWD_USERNAME and PDFCROWD_API_KEY before running this command. The account is saved for all converters. Missing credentials cause an error.

Example:
  • pdf2image auth login --non-interactive

auth status

Show which credentials will be used without revealing the API key.

This reads local settings; it does not verify the account with PDFCrowd.

Usage:
pdf2image auth status
pdfcrowd auth status

auth logout

Remove the saved account for all converter commands.

Credential environment variables still apply when set.

Usage:
pdf2image auth logout
pdfcrowd auth logout

Help and Version

help [TOPIC|OPTION|CATEGORY]

Show offline help for this converter.

Help does not load saved settings or credentials and does not contact the service.

TOPIC|OPTION|CATEGORY: Omit the argument for an overview. Supply one topic, option name (with or without --), or conversion category ID.

  • all: List every option.
  • categories: List help topics and conversion option groups.
  • syntax: Explain how to supply arguments.
  • configuration: Save and load conversion defaults.
  • authentication: Set up your PDFCrowd account.
  • input-output: Read inputs and save results.
  • exit-codes: Check whether a command succeeded.
Usage:
pdf2image help [TOPIC|OPTION|CATEGORY]
pdfcrowd help pdf2image [TOPIC|OPTION|CATEGORY]
Examples:
  • pdf2image help all
  • pdf2image help categories
  • pdf2image help --output
help --json

This option applies only to help.

Print help as JSON for scripts, integrations, and AI agents.

Includes option names, argument types, defaults, allowed values, authentication rules, and exit codes. Works offline.

Example:
  • pdf2image help --json

--help, -h

Show a summary of commands and options.

Use help all for every option, or help OPTION for details.

Example:
  • pdf2image --help

--version, -V

Show the PDFCrowd CLI version.

Example:
  • pdf2image --version

Conversion Format

--output-format

The output file format.

Syntax:
--output-format OUTPUT_FORMAT
Default:
png
Allowed Values:
  • png
  • jpg
  • gif
  • tiff
  • bmp
  • ico
  • ppm
  • pgm
  • pbm
  • pnm
  • psb
  • pct
  • ras
  • tga
  • sgi
  • sun
  • webp

General Options

--pdf-password

Password to open the encrypted PDF file.

Syntax:
--pdf-password PASSWORD

--print-page-range

Set the page range to print.

Syntax:
--print-page-range PAGES
Constraint:
  • A comma separated list of page numbers or ranges.
Examples:
  • Just the second page is printed: "2"
  • The first and the third page are printed: "1,3"
  • Everything except the first page is printed: "2-"
  • Just the first 3 pages are printed: "-3"
  • Pages 3, 6, 7, 8 and 9 are printed: "3,6-9"

--dpi

Set the output graphics DPI. Higher values increase quality but also file size. Use 72-96 for screen, 150 for web, 300 for print.

Availability:
Converter >= 20.10. See versioning.
Syntax:
--dpi DPI
Default:
144

--force-zip

Enforce the zip output format. Get output as zip even for single images. Useful for consistent file handling in automated workflows.

Syntax:
--force-zip[=true|false]
Default:
false
Allowed Values:
  • true
  • false

--use-cropbox

Use the crop box rather than media box. Respects PDF crop settings for trimmed output. Use when PDFs have defined crop boundaries.

Syntax:
--use-cropbox[=true|false]
Default:
false
Allowed Values:
  • true
  • false

--crop-area-x

Set the top left X coordinate of the crop area in pixels at the selected DPI, measured from the left edge of the rendered page.

Syntax:
--crop-area-x X
Constraint:
  • Must be a positive integer or 0.
Example:
  • Start crop 100 pixels from the left edge: 100

--crop-area-y

Set the top left Y coordinate of the crop area in pixels at the selected DPI, measured from the top edge of the rendered page.

Syntax:
--crop-area-y Y
Constraint:
  • Must be a positive integer or 0.
Example:
  • Start crop 100 pixels from the top edge: 100

--crop-area-width

Set the width of the crop area in pixels at the selected DPI.

Syntax:
--crop-area-width WIDTH
Constraint:
  • Must be a positive integer or 0.
Default:
PDF page width.
Example:
  • Set crop width to 100 pixels: 100

--crop-area-height

Set the height of the crop area in pixels at the selected DPI.

Syntax:
--crop-area-height HEIGHT
Constraint:
  • Must be a positive integer or 0.
Default:
PDF page height.
Example:
  • Set crop height to 100 pixels: 100

--crop-area

Set the crop area to extract part of a PDF page. Coordinates and dimensions are in pixels at the selected DPI, measured from the top left of the rendered page. When changing DPI, scale all four values by the same ratio to keep the same region.

Syntax:
--crop-area X Y WIDTH HEIGHT
Constraint:
  • Must be a positive integer or 0.
Constraint:
  • Must be a positive integer or 0.
Constraint:
  • Must be a positive integer or 0.
Constraint:
  • Must be a positive integer or 0.

--use-grayscale

Generate a grayscale image.

Syntax:
--use-grayscale[=true|false]
Default:
false
Allowed Values:
  • true
  • false

Miscellaneous

--debug-log

Turn on debug logging to troubleshoot conversion issues. Details about the conversion process, including resource loading, rendering steps, and error messages are stored in the debug log. Use this when conversions fail or produce unexpected results.

Syntax:
--debug-log[=true|false]
Default:
false
Allowed Values:
  • true
  • false

--tag

Tag the conversion with a custom value for tracking and analytics. Use this to categorize conversions by customer ID, document type, or business unit. The tag appears in conversion statistics. A value longer than 32 characters is cut off.

Syntax:
--tag TAG
Example:
  • Track job in analytics: "client-1234"

--http-proxy

A proxy server used by the conversion process for accessing the source URLs with HTTP scheme. This can help circumvent regional restrictions or provide limited access to your intranet.

Syntax:
--http-proxy PROXY
Constraint:
  • The value must have format DOMAIN_OR_IP_ADDRESS:PORT.
Examples:
  • Corporate proxy server: "myproxy.com:8080"
  • Direct IP proxy connection: "113.25.84.10:33333"

--https-proxy

A proxy server used by the conversion process for accessing the source URLs with HTTPS scheme. This can help circumvent regional restrictions or provide limited access to your intranet.

Syntax:
--https-proxy PROXY
Constraint:
  • The value must have format DOMAIN_OR_IP_ADDRESS:PORT.
Examples:
  • Secure proxy for HTTPS: "myproxy.com:443"
  • Direct secure proxy IP: "113.25.84.10:44333"

API Client Options

--use-http

Specify whether to use HTTP or HTTPS when connecting to the PDFCrowd API.

Syntax:
--use-http[=true|false]
Default:
false
Allowed Values:
  • true
  • false

--client-user-agent

Specify the User-Agent HTTP header the CLI sends to the PDFCrowd API.

Syntax:
--client-user-agent AGENT
Default:
pdfcrowd_cli_client/1.1.0 (https://pdfcrowd.com)

--proxy

Specify an HTTP proxy the CLI uses to connect to the PDFCrowd API.

Syntax:
--proxy HOST PORT USER_NAME PASSWORD

--retry-count

Specify the number of automatic retries when a 502 or 503 HTTP status code is received. The status code indicates a temporary network issue. This feature can be disabled by setting to 0.

Syntax:
--retry-count COUNT
Default:
1
Example:
  • Retry failed requests three times: 3