Puppeteer PDF Paper Sizes and Formats

Puppeteer’s page.pdf() accepts named paper sizes through format. Letter is the default. Use format: 'A4' for A4, or set width and height with units for a custom size. If the page declares its own size in CSS @page, set preferCSSPageSize: true to let that rule take priority.

Choose a Puppeteer PDF paper size

Use a named format when one of Puppeteer’s documented formats fits the output you need. Use explicit dimensions for other sizes. If the page’s print stylesheet owns the page size, enable CSS sizing so Puppeteer does not scale it to the configured paper.

const { chromium } = require('playwright');

The snippet above is not Puppeteer code; use this complete Puppeteer example instead. Install Puppeteer with npm install puppeteer, then save the following as pdf.js:

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch({ headless: true });
  try {
    const page = await browser.newPage();
    await page.goto('https://example.com', { waitUntil: 'networkidle2' });

    await page.pdf({
      path: 'output.pdf',
      format: 'A4',
      printBackground: true,
      margin: {
        top: '12mm',
        right: '12mm',
        bottom: '12mm',
        left: '12mm',
      },
    });
  } finally {
    await browser.close();
  }
})();

Run it with node pdf.js. Replace A4 with another supported format, or use width and height for custom dimensions. See Puppeteer’s PDFOptions reference and PaperFormat reference.

Named formats and dimensions

The current Puppeteer PaperFormat reference documents the following names and dimensions. Dimensions are width × height; choose landscape separately when the content should be horizontal.

Format	Width × height (inches)	Width × height (centimeters)
Letter	8.5 × 11	21.59 × 27.94
Legal	8.5 × 14	21.59 × 35.56
Tabloid	11 × 17	27.94 × 43.18
Ledger	17 × 11	43.18 × 27.94
A0	33.1102 × 46.811	84.1 × 118.9
A1	23.3858 × 33.1102	59.4 × 84.1
A2	16.5354 × 23.3858	42 × 59.4
A3	11.6929 × 16.5354	29.7 × 42
A4	8.2677 × 11.6929	21 × 29.7
A5	5.8268 × 8.2677	14.8 × 21
A6	4.1339 × 5.8268	10.5 × 14.8

These are the values in Puppeteer’s API reference, which describes valid paper format types for PDF output. Treat them as Puppeteer’s implementation reference. The list does not by itself guarantee printer compatibility or determine suitable margins for a particular document.

Set a custom PDF page size

When the desired dimensions are not in the named list, set both width and height. Each accepts a number or a string with a unit. Strings make the intended measurement explicit:

await page.pdf({
  path: 'custom.pdf',
  width: '180mm',
  height: '250mm',
  printBackground: true,
});

Use a unit such as in, cm, mm, or px in dimension strings. Avoid mixing assumptions about units: record the intended physical dimensions and provide them explicitly so the PDF page size is unambiguous.

How format, dimensions, and CSS @page interact

These settings are related, but have a defined priority:

• format selects a named paper format. When provided, it takes priority over width and height.
• If no format is supplied, the documented default is Letter.
• preferCSSPageSize: true gives a CSS @page size priority over format, width, or height.
• With preferCSSPageSize: false, the default, Puppeteer scales the page content to fit the selected paper size when needed.

For example, let the document’s print stylesheet set the size:

// In the page stylesheet:
// @page { size: A4 landscape; margin: 12mm; }

await page.pdf({
  path: 'css-sized.pdf',
  preferCSSPageSize: true,
  printBackground: true,
});

If you want Puppeteer’s explicit format or dimensions to control the page instead, omit preferCSSPageSize: true and keep the CSS @page rule aligned with that choice or remove its size declaration.

Orientation, margins, scale, and print styling

Paper size determines the page dimensions. These additional options control how content is laid out or painted:

Option	Documented behavior	When to set it
landscape	Defaults to false.	Set true for a horizontal page orientation.
margin	Margins default to none.	Set top, right, bottom, and left margins with unit strings when content needs a margin.
scale	Defaults to 1; accepted range is 0.1–2.	Adjust content scale if required, while checking legibility and page breaks.
printBackground	Defaults to false.	Set true when background colors or images should appear in the PDF.
Media type	page.pdf() uses print CSS media.	Call page.emulateMediaType('screen') before PDF generation if the screen stylesheet is intended.

For exact print colors, Puppeteer documents the CSS property -webkit-print-color-adjust. A page can otherwise alter colors for printing. Paper size alone does not resolve print margins, color treatment, or page-break behavior; validate those against the actual document stylesheet.

Common problems and fixes

Symptom	Likely cause	Fix
The PDF comes out Letter instead of the requested size.	format is missing, so the documented default is Letter, or a supplied format overrides dimensions.	Set the intended format, or remove it and supply both width and height.
The PDF ignores the CSS @page dimensions.	preferCSSPageSize is false, its default.	Set preferCSSPageSize: true and make sure the page actually declares the desired size in @page.
Content is unexpectedly scaled.	The CSS page size does not match the selected PDF size and Puppeteer is fitting content to the selected paper.	Align CSS and PDF options, or set preferCSSPageSize: true when CSS should own the size.
Backgrounds are missing.	printBackground defaults to false.	Set printBackground: true.
Layout differs from the browser screen.	PDF generation applies print media styles by default.	Use print-specific CSS, or call page.emulateMediaType('screen') before creating the PDF.
Colors look different in the PDF.	Print color adjustment can change colors.	Apply -webkit-print-color-adjust in the relevant print CSS where exact colors are required.
Custom dimensions are wrong or hard to reason about.	Dimensions were supplied without clear units or only one dimension was set.	Set both dimensions and use explicit units, for example width: '180mm' and height: '250mm'.

Performance, reliability, and cost

PDF generation runs a browser page and depends on its load and print layout. Wait for the content your document needs before calling page.pdf(); a navigation wait condition alone may not mean that every application-rendered chart, image, or font is ready. For repeatable output, keep the page content, print CSS, paper-size settings, and media choice explicit. Close the browser in a finally block so it is cleaned up if PDF creation fails.

The research dossier provides no Puppeteer timing benchmark or runtime cost figures, so throughput and infrastructure cost depend on the page, browser environment, and workload. When processing many documents, measure your own representative pages and control concurrency to fit available memory and CPU. The output paper size itself does not establish performance or guarantee compatibility with a downstream printer.

Or skip the browser setup

If you need a page capture as an image or PDF rather than a Puppeteer-controlled document, ScreenshotNeo is a website screenshot API and MCP server for developers. One GET request returns PNG, JPEG, WebP, or PDF. For a PDF, use the documented format=pdf parameter; see the API docs for the request options.

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

Cookie banners, newsletter popups, and chat widgets are removed before the shot. Bot checks, blank pages, and failed loads are never billed. An MCP server lets AI agents use screenshot tools. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Every feature is on every plan. Sign up for 1,000 free screenshots a month, with no card.

FAQ

What paper size does Puppeteer use if I set no size options?

Letter is the documented default format.

Can I use a named format and custom dimensions together?

You can supply both, but format takes priority over width and height. Choose one sizing route for predictable results.

Does A4 require a custom width and height?

No. A4 is a named format, so use format: 'A4'.

How do I make the CSS page size control the PDF?

Declare the size in CSS @page and set preferCSSPageSize: true.

Does Puppeteer’s format list guarantee the right choice for my printer?

No. The list documents Puppeteer’s PDF format options. Check the requirements of the document’s destination and printer separately.