HTML to PDF Command Line Tool

Overview

Convert web pages and HTML files to PDF from your terminal or shell scripts with html2pdf. The command sends your input to PDFCrowd's servers and saves the converted PDF 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

Convert a web page and save it as example.pdf:

html2pdf --content-viewport-width=balanced \
    --output example.pdf \
    https://example.com/

The balanced viewport setting fits the HTML viewport to the print area.

Convert an HTML File

Upload an existing document.html file and save the PDF as document.pdf:

html2pdf --content-viewport-width=balanced \
    --output document.pdf \
    document.html

For HTML that references local images or stylesheets, see Include Local Assets.

Configure a Conversion

Choose an Input

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 Content

Send HTML through stdin and save the PDF as report.pdf:

html2pdf \
    --content-viewport-width=balanced \
    --output report.pdf \
    - <<'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.

Include Local Assets

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.pdf:

(cd document && zip -q -r - .) > document.zip &&
html2pdf \
    --content-viewport-width=balanced \
    --output document.pdf \
    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 Conversion Settings

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

Use landscape Letter pages with half-inch margins:

html2pdf --content-viewport-width=balanced \
    --margin-bottom=0.5in \
    --margin-left=0.5in \
    --margin-right=0.5in \
    --margin-top=0.5in \
    --orientation=landscape \
    --page-size=Letter \
    --output page-layout.pdf \
    https://example.com/

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

Convert Non-Public Pages

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:

• Send HTML or upload files. If you can generate or save the page's HTML locally, including a page behind a login, send the HTML content or upload an HTML file. Sending HTML does not automatically include its images, stylesheets, or scripts. These must be accessible to PDFCrowd or included in an archive with the HTML.
• Provide website authentication. For a website reachable over the internet that requires authentication, use --http-auth, --cookies, or --custom-http-header, as required by the site. These authenticate access to the source website, separately from your PDFCrowd account.
• Use a tunnel. To convert a running local application by URL, use a tool such as LocalTunnel to give its server a public URL, then pass that URL to html2pdf. Referenced resources must also be accessible through the tunnel or another reachable URL. Any website authentication still applies.

Handle the Result

Choose an Output

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. PDF output requires a file, redirection, or pipe; html2pdf refuses to send it 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 html2pdf help exit-codes for the process exit-code mapping.

Read Conversion Information

Add --print-page-count to report the PDF's page count, or --print-remaining-credit-count to report the remaining credits after conversion.

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.

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.

Troubleshooting

Inspect a Conversion

Enable --debug-log and request --print-debug-log-url. This example saves the converted PDF as response.body and prints the debug-log URL to stderr:

html2pdf --print-debug-log-url \
    --content-viewport-width=balanced \
    --debug-log \
    --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.

Common Problems

• For missing images or styles, check resource URLs and access to non-public pages, or package local assets.
• For missing dynamic content, use --wait-for-element or --javascript-delay and inspect the debug log.
• For unexpected layout, adjust --content-viewport-width or enable --use-print-media when the page supplies print styles.
• For unexpected saved settings, inspect --show-config or bypass conversion defaults with --no-config.

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