Convert web pages and HTML files to images from your terminal or shell scripts with
html2image. The command sends your input to PDFCrowd's servers and saves the
converted image locally.
Install the command-line client with pip, or see other installation options.
python -m pip install pdfcrowd-cli
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 web page and save it as example.png:
html2image --output-format=png \ --output example.png \ https://example.com/
Upload an existing document.html file and save the image as document.png:
html2image --output-format=png \ --output document.png \ document.html
For HTML that references local images or stylesheets, see Include Local Assets.
Pass a web page URL, a local HTML file, or an archive as the input. Use - to read
HTML from stdin, including input piped from another program. See
Conversion Input
for the supported forms.
Send HTML through stdin and save the PNG as
report.png:
html2image --output-format=png \ --output report.png \ - <<'HTML' <!doctype html> <html><body><h1>Monthly report</h1></body></html> HTML
For relative resource URLs, add <base href="https://your-site.example/">
to the HTML head, replacing the address with your public website URL, or use absolute URLs.
For HTML templates and structured data, see
template rendering.
Package HTML and its local images, stylesheets, and scripts in an archive, keeping their
relative paths. This example requires the zip utility and assumes an existing
document directory containing your HTML file and any local assets.
It creates document.zip and converts it to
document.png:
(cd document && zip -q -r - .) > document.zip && html2image --output-format=png \ --output document.png \ document.zip
When the archive has multiple HTML files, use
--zip-main-filename to select the main document.
See the archive examples
for prepared archives and main-file selection.
Add options before the input. Command-line options override saved conversion defaults.
Capture a 1280-pixel-wide viewport and scale the PNG output to 50%:
html2image --output-format=png \ --scale-factor=50 \ --screenshot-width=1280 \ --output customized.png \ https://example.com/
| Purpose | Options |
|---|---|
| Image format | --output-format |
| Screenshot dimensions and scaling | --screenshot-width, --screenshot-height, --scale-factor |
| Background color | --background-color |
| Page styles and content | --custom-css, --custom-javascript, --use-print-media |
| Wait for dynamic content | --wait-for-element, --javascript-delay |
The default screenshot width is 1024 pixels. When no height is set, the image uses the document height.
See the command reference for all options and Configuration for saved defaults. For more tasks, browse the CLI examples.
Conversion runs on PDFCrowd's servers. They cannot directly access your
localhost or private network, and a website may require a login.
Choose an approach that suits your page:
--http-auth,
--cookies, or
--custom-http-header, as required by the site.
These authenticate access to the source website, separately from your PDFCrowd
account.
html2image.
Referenced resources must also be accessible through the tunnel or another
reachable URL. Any website authentication still applies.
The default output format is PNG. Use --output-format=jpg for JPEG, or select
another supported format from --output-format.
Match the output filename extension to the selected format.
The examples save the result with
--output PATH.
This preserves an existing file if conversion fails. Shell redirection
(>) opens or truncates its destination before the command runs.
Use --output - to pipe the result to another command.
See the output reference
for terminal behavior and conversion information.
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.
Read stderr for the diagnostic message. See errors and exit codes for the meaning of the exit status and reported API errors.
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.
The maximum size for any created image is 65 megapixels. Images exceeding this size are cropped vertically to meet this limit.
PDFCrowd stops a conversion that exceeds 60 seconds of processing time.
Reason code 323 identifies this HTML conversion timeout.
Check for slow resource downloads or long-running JavaScript. Allowing your
application to wait longer does not extend the server's processing limit.
Enable --debug-log and request
--print-debug-log-url.
This example saves the converted PNG as response.body and prints the
debug-log URL to stderr:
html2image --print-debug-log-url \ --debug-log \ --output-format=png \ --output response.body \ https://example.com/
The debug log includes resource-loading details, timeouts, and browser console messages. You can also find logs in your conversion history. A local or connection failure may occur before a conversion log is available.
--wait-for-element or --javascript-delay and inspect the debug log.--screenshot-width, --screenshot-height, and --scale-factor. For cropped tall images, see Limits and Retries.--show-config or bypass conversion defaults with --no-config.
For help, contact support
with available diagnostics, the version from html2image --version,
and enough detail to reproduce the problem.