ScreenshotNeo

BlogHow-to

How to Save a Landscape PDF with Chrome’s Command-Line Flags

Chrome can print PDFs from Headless, but no documented --landscape flag exists. Use print CSS or DevTools for reliable landscape output.

By the ScreenshotNeo team30 September 20269 min read

How to Save a Landscape PDF with Chrome’s Command-Line Flags

Short answer: Chrome’s documented Headless command-line interface can create a PDF with --print-to-pdf, but it does not document a --landscape flag. If you need guaranteed landscape output, use print CSS when you control the page or call the DevTools print-to-PDF API with landscape: true. The CLI still handles many unattended exports well.

This guide shows the exact commands, explains why viewport flags do not rotate paper, and gives a repeatable automation path. It also covers timing, headers and footers, authentication, failure diagnosis, and a hosted option when maintaining Chrome is not worth the effort.

1. What Chrome’s command line can and cannot do

Chrome for Developers documents --print-to-pdf as a Headless flag that saves the target page as output.pdf in the current working directory. The same reference documents --no-pdf-header-footer for removing the printed date, time, URL and page number. It does not document a command-line switch that sets paper orientation. See the Chrome Headless command-line reference.

That distinction matters because flags such as --window-size=1600,900 change the browser viewport used to render the page; they do not prove that the PDF media is landscape. A wide viewport can still produce portrait pages. Likewise, --timeout and --virtual-time-budget affect when Chrome prints, not the page orientation.

Goal Supported route What to verify
Create a basic PDF --print-to-pdf output.pdf appears in the working directory
Remove browser print chrome --no-pdf-header-footer No date, URL or page number header/footer
Set orientation in code DevTools Protocol print parameter landscape: true Page width is greater than page height
Set orientation in a page you own @page { size: landscape; } Inspect the resulting PDF on your Chrome version

2. Basic landscape attempt from the shell

Start with the documented command. Run it from a writable directory so the default file is easy to find:

The capture path: page rendering, print settings and the final landscape PDF.
The capture path: page rendering, print settings and the final landscape PDF.
mkdir -p pdf-output
cd pdf-output
chrome --headless --print-to-pdf https://example.com/

On systems where the executable is named differently, substitute google-chrome, chromium or the full path to your installation. The result is output.pdf. To suppress the default header and footer:

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

Do not append --landscape and assume it is supported. An unknown or ignored switch can leave you with a portrait document while your script reports success. If orientation is a requirement, measure the PDF after creation or use the print API shown below.

Choose an explicit output location

Chrome’s documented example uses the default name. In automation, isolate each run in its own directory and rename the result after the process exits:

work=$(mktemp -d)
chrome --headless --print-to-pdf --no-pdf-header-footer https://example.com/ >"$work/chrome.log" 2>&1
if [ -f "$work/output.pdf" ]; then
  mv "$work/output.pdf" ./example-landscape.pdf
else
  echo "Chrome did not create output.pdf" >&2
  exit 1
fi

The command above does not force landscape; the filename is only an operational convenience. Use a PDF inspection step such as pdfinfo and check that the reported page size has width greater than height.

3. Make the page landscape with print CSS

If you own the HTML, put the orientation in the print stylesheet:

<style>
@media print {
  @page { size: landscape; margin: 12mm; }
  body { margin: 0; }
  .screen-only { display: none !important; }
}
</style>

Then run the same --print-to-pdf command. This is page-side behavior, not a documented CLI guarantee. Framework styles, nested print rules, and browser-version differences can change the final result, so inspect a representative PDF. Keep important content inside the printable area and use print-specific widths instead of relying on a very wide screen layout.

CSS details that prevent clipped pages

  • Use physical margins in mm or in and leave room for printer-safe areas.
  • Prefer fixed column widths that fit the landscape content box; avoid a single unbroken flex row.
  • Add break-inside: avoid to cards and table rows where splitting would be confusing.
  • Use overflow-wrap: anywhere for long URLs and IDs.
  • Hide navigation, cookie notices and interactive controls in print media.
  • Check backgrounds and colors with the print settings of the route you use; headless output can differ from an interactive print preview.

4. Reliable orientation with the DevTools print API

Chromium’s DevTools Protocol test passes a landscape boolean to the print-to-PDF command and verifies that the rendered page is wider than it is tall. That is evidence for the protocol parameter, not for a Chrome command-line flag. The pinned test is in Chromium’s devtools_printtopdf_browsertest.cc.

One practical implementation is Puppeteer, which drives Chrome and exposes the print option:

import puppeteer from 'puppeteer';

const browser = await puppeteer.launch({headless: 'new'});
try {
  const page = await browser.newPage();
  await page.goto('https://example.com/', {waitUntil: 'networkidle2', timeout: 90000});
  await page.pdf({
    path: 'example-landscape.pdf',
    format: 'A4',
    landscape: true,
    printBackground: true,
    displayHeaderFooter: false,
    margin: {top: '12mm', right: '12mm', bottom: '12mm', left: '12mm'}
  });
} finally {
  await browser.close();
}

Set preferCSSPageSize: true when the document’s @page rule should win. Otherwise, the API’s format, margins and orientation define the paper box. Pin a Chrome and Puppeteer version in CI, and validate the generated dimensions after upgrades.

Direct DevTools Protocol flow

If you already manage a Chrome debugging session, call the Page.printToPDF command over the DevTools Protocol. The important fields are landscape: true, printBackground: true, margins, and optionally pageRanges. The protocol returns base64 PDF data; decode it to a file and inspect the page size. The exact transport (WebSocket, client library and launch flags) varies by your automation stack, so use its current API documentation rather than copying an old endpoint.

5. Timing, dynamic pages and authenticated content

A PDF is a snapshot. Single-page applications may still be rendering when Chrome prints. The CLI reference documents --timeout=5000 as a maximum wait example and --virtual-time-budget for fast-forwarding time-dependent scripts. Neither proves that a specific site’s data, fonts or lazy images are ready.

For repeatable output:

  1. Wait for navigation plus the application’s own ready signal (for example, a dashboard element).
  2. Wait for fonts and images, or use a network-idle condition with a bounded timeout.
  3. Freeze animations and transitions in print CSS.
  4. Use a final short delay only as a safety margin, not as the primary readiness test.
  5. Capture a diagnostic screenshot or HTML log when a run fails.

For pages requiring login, launch a controlled profile or inject cookies and headers through your automation library. Never put credentials in a URL that can appear in shell history or logs. Redact tokens in CI output and delete temporary profiles after the run.

6. Troubleshooting checklist

Symptom Likely cause Fix
--landscape has no effect It is not a documented Headless CLI option. Use print CSS or a print API with landscape: true; then inspect dimensions.
PDF is portrait despite a wide page Viewport width was mistaken for paper orientation. Set the print parameter or @page size and remove assumptions about --window-size.
Output file is missing Wrong working directory, unwritable directory, crash or navigation failure. Use an absolute working directory, capture stderr, check the exit code and look for output.pdf.
Header or URL appears Header/footer suppression was omitted or spelling differs on an older Chrome. Try --no-pdf-header-footer; older releases may use --print-to-pdf-no-header.
Blank or partial PDF App content was not ready, blocked, or timed out. Wait for a selector, extend the bounded timeout, check console/network errors and authenticate correctly.
Text or images are clipped Content exceeds the landscape content box or a print rule forces overflow. Reduce margins/column widths, add wrapping and break rules, and test long data.
Fonts differ from local output Fonts were not installed or loaded before print. Bundle or install the font, wait for document.fonts.ready, and avoid relying on a developer laptop.
Pages vary between runs Animations, ads, live data or responsive breakpoints changed. Freeze motion, block nonessential resources in automation, set a fixed viewport and record the input version.

7. Performance, reliability and cost

Launching a new browser for every URL is simple but expensive in time and memory. A long-running worker can reuse one browser and create an isolated page or context per job. Bound navigation, selector waits and total job duration so a broken origin cannot exhaust workers. Limit concurrency to what the host can handle; more tabs can increase memory pressure and make layout timing less predictable.

Cache stable assets where policy permits, but do not cache personalized responses across users. Record the URL, Chrome version, viewport, CSS revision, wait condition and PDF byte size alongside each artifact. For critical documents, keep a checksum and a small set of visual regression samples. Treat a zero exit code as process success only; verify that the file exists, is parseable and has the expected orientation and page count.

The local CLI has no per-page service charge, but you pay for your own compute, browser maintenance, storage and engineering time. A hosted capture API can be cheaper operationally when you need bursts, many sites or consistent cleanup of consent UI.

8. Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server. Its PDF endpoint accepts the same URL request pattern as the image API, so you can generate a PDF without packaging Chrome, fonts or a worker fleet. See the ScreenshotNeo documentation for the current request options.

Consent UI and overlays can be removed before a hosted capture.
Consent UI and overlays can be removed before a hosted capture.

cURL:

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

Python:

import requests; r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90); open("shot.webp", "wb").write(r.content)

Node.js:

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' }); const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

For a PDF, request the PDF output option described in the docs and save the response with a .pdf extension. ScreenshotNeo can set paper size, margins, landscape mode and page ranges, and it supports full-page capture, custom CSS and JavaScript, waits, headers, cookies, user agents, timezone and geolocation. It can also capture one CSS-selected element, hide selectors, block ads/trackers/requests/resource types, resize images, cache with a chosen TTL, create signed links, run async jobs with signed webhooks, capture up to 100 URLs per bulk call and expose usage data.

The cleanup behavior is useful for documents assembled from public pages: it accepts cookie or consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups and chat widgets. Each cleanup step can be disabled. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads and cache hits are not billed; response headers identify the page verdict and whether the request was billed.

An MCP server provides take_screenshot, get_page_info and capture_pdf tools for Claude, Cursor and other MCP clients. Free usage is 1,000 shots per month with no card; paid plans start at $5 for 3,000 shots, and every feature is on every plan. Start with the free ScreenshotNeo account.

9. A production decision checklist

  • Do you control the page? If yes, add and verify @page { size: landscape; }.
  • Do you need an explicit programmatic guarantee? Use a print API with landscape: true.
  • Are headers, cookies, popups or bot checks involved? Plan cleanup and authentication before printing.
  • Can you verify output? Check file existence, parseability, dimensions and page count.
  • Is browser operations work the bottleneck? Compare your compute and maintenance cost with a hosted capture service.

10. FAQ

Can I use --window-size to make the PDF landscape?

No. It changes the viewport. Orientation belongs to print CSS or the print API.

What is Chrome’s default PDF filename?

The documented default is output.pdf in the current working directory.

Will --virtual-time-budget wait for API data?

It advances virtual time for scripts; it does not guarantee that a particular network request or application state is complete. Use an explicit ready condition.

Which route is easiest for many unrelated sites?

A hosted capture API avoids browser installation and profile management. ScreenshotNeo adds consent and popup cleanup, verdict headers and an MCP server for agent workflows.

How do I prove a PDF is landscape in CI?

Parse the PDF and assert that each target page has width greater than height. Keep a sample artifact when the assertion fails.