Chrome headless print to PDF (--print-to-pdf)

Chrome headless print to PDF with --print-to-pdf. Save HTML or a URL as PDF, remove the header and footer, set page size, and know when to use an API.

Chrome can print any page to PDF from the command line, with no Node.js or Python code. It is the quickest way to get a Chromium-quality PDF from a script or a cron job. This page covers the flags that work, what the CLI can't do, and what to use when you outgrow it.

Quick answer. Run Chrome in headless mode with --print-to-pdf and the page you want.

google-chrome --headless --print-to-pdf=page.pdf --no-pdf-header-footer https://example.com

The basic command

This is the command for each operating system.

# macOS
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
  --headless --print-to-pdf=page.pdf https://example.com

# Linux
google-chrome --headless --print-to-pdf=page.pdf https://example.com

# Windows (PowerShell)
& "C:\Program Files\Google\Chrome\Application\chrome.exe" `
  --headless --print-to-pdf="C:\temp\page.pdf" https://example.com

Without a value, --print-to-pdf writes output.pdf in the current directory. Chromium and Edge accept the same flags (chromium, msedge).

Convert a local HTML file

To print a file on disk, pass a file:// URL with an absolute path.

google-chrome --headless --print-to-pdf=invoice.pdf "file://$PWD/invoice.html"

Relative images and stylesheets resolve against the file's folder, so keep assets next to the HTML.

Remove the date, title and URL header and footer

This flag gives you a clean page with no browser header or footer. By default Chrome prints the date and title at the top and the URL and page number at the bottom.

google-chrome --headless --print-to-pdf=page.pdf --no-pdf-header-footer https://example.com

Older Chrome versions called this flag --print-to-pdf-no-header. If the header still shows up, check your Chrome version and try the old name.

Page size, margins and landscape

This section shows how to control the page layout. The CLI has no --paper-size or --landscape flag, so set the page in CSS instead and Chrome follows it.

@page {
  size: A4 landscape;   /* or: Letter, 210mm 297mm, ... */
  margin: 15mm;
}
html { -webkit-print-color-adjust: exact; print-color-adjust: exact; } /* keep background colors */

This only works for HTML you control. For someone else's URL, you get whatever their print stylesheet says.

Wait for JavaScript before printing

This section helps when charts or client-side content appear after load. Chrome prints as soon as the page has loaded, so give late content time to arrive.

google-chrome --headless --print-to-pdf=page.pdf \
  --virtual-time-budget=10000 https://example.com/dashboard

--virtual-time-budget fast-forwards timers by up to that many milliseconds before printing. --timeout=5000 caps the wait in real time. Neither knows when your page is actually ready. For that you need a script that waits for a condition.

Common problems

These are the issues people hit most, with the fix for each.

• Running as root in Docker. Chrome refuses to start with its sandbox. Use a non-root user, or add --no-sandbox only in an isolated container.
• Old headless vs new headless. Modern Chrome uses the "new" headless mode, and the old one ships separately as chrome-headless-shell. Flag behavior has changed between versions, so pin your Chrome version in CI.
• Missing fonts. Servers often lack the fonts your HTML uses. Install them or load web fonts with @font-face.
• Blank or cut-off pages. The cause is usually a fixed-height container or overflow: hidden on body. Remove them for print and use break-inside: avoid on blocks that shouldn't split. See page breaks.

When the CLI isn't enough: Puppeteer and Playwright

This section shows the next step up from the CLI. For custom headers with page numbers, paper size from code, waiting on a selector, or returning bytes to a web request, you need the DevTools protocol. Here it is in Node.js.

import puppeteer from "puppeteer";
const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.goto("https://example.com", { waitUntil: "networkidle0" });
await page.pdf({ path: "page.pdf", format: "A4", landscape: true, printBackground: true });
await browser.close();

Playwright's page.pdf() takes nearly the same options (Chromium only). For the full walkthrough, see Puppeteer HTML to PDF.

Easier: one API call, no Chrome to install

This section shows how to get the same output without running Chrome yourself. html-pdf.com runs headless Chromium for you and exposes the print options the CLI is missing.

curl -X POST https://html-pdf.com/v1/pdf \
  -H "Authorization: Bearer $HTML_PDF_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "url": "https://example.com",
        "format": "A4",
        "landscape": true,
        "margin": "15mm",
        "media": "screen",
        "wait_for_expression": "window.chartsReady === true",
        "footer_html": "<div style=\"font-size:9px;width:100%;text-align:center\">Page <span class=\"pageNumber\"></span> of <span class=\"totalPages\"></span></div>"
      }' \
  -o page.pdf

To convert a local HTML file with its images and CSS, upload them together.

curl -X POST https://html-pdf.com/v1/pdf \
  -H "Authorization: Bearer $HTML_PDF_KEY" \
  -F "index.html=@invoice.html" \
  -F "logo.png=@logo.png" \
  -F 'options={"format":"A4","margin":"15mm"}' \
  -o invoice.pdf

Get a key, then open the link we email you to confirm your address. That adds 100 free credits (1 credit = 1 page).

curl -X POST https://html-pdf.com/v1/signup -H "Content-Type: application/json" -d '{"email": "you@example.com"}'

Failed renders cost nothing. The full reference is in the API docs. Prefer to self-host? See running Gotenberg in Docker.

FAQ

How do I print a web page to PDF with headless Chrome?

Run google-chrome --headless --print-to-pdf=page.pdf https://example.com. Add --no-pdf-header-footer to drop the date, title and URL.

How do I set landscape or A4 with --print-to-pdf?

The CLI has no paper size flag. Put @page { size: A4 landscape; } in your CSS, or use an API with format and landscape options.

Does Chrome support CSS page breaks and @page margin boxes?

Yes. Chromium honors break-before, break-inside: avoid and @page rules, and Chrome 131+ also supports @page margin boxes. See page breaks.

Is there a free API instead of installing Chrome?

Yes. html-pdf.com gives you 100 free credits once, with no card, and 1 credit = 1 PDF page. Purchased credits never expire.