How to Set Margins When Saving PDFs with Puppeteer

Set margins in the options object passed to page.pdf(). Use a margin object with top, right, bottom, and left values. Unit-bearing strings make the intended dimensions explicit:

await page.pdf({
  path: 'output.pdf',
  margin: {
    top: '1in',
    right: '0.75in',
    bottom: '1in',
    left: '0.75in',
  },
});

Omitting margin means no margins are set. For predictable padding, specify all four sides. See Puppeteer’s PDFOptions reference and PDFMargin reference.

1. Complete runnable example

Install Puppeteer, save this as make-pdf.mjs, then run node make-pdf.mjs. The example loads a page and writes a PDF with independently configured margins.

import puppeteer from 'puppeteer';

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

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

The margin values are strings with explicit units. The documentation supports string or numeric side values, but does not specify numeric units in the consulted reference, so use unit-bearing strings when clarity matters. printBackground controls whether background graphics are included; it does not set the page margins.

2. Configure paper size, CSS page size, and media

Margins are only one part of PDF layout. Choose the paper dimensions and rendering media deliberately.

Paper format: Puppeteer’s documented default is Letter. Set format: 'A4' or another supported standard format when the output needs a particular paper size. See PaperFormat.
CSS @page dimensions: preferCSSPageSize defaults to false, so content is scaled to fit the selected paper size. Set it to true when CSS @page dimensions should take priority over width, height, or format.
Print or screen styles: page.pdf() uses print media by default. To render screen styles instead, call await page.emulateMediaType('screen') before generating the PDF.

await page.emulateMediaType('screen');
await page.pdf({
  path: 'screen-layout.pdf',
  format: 'A4',
  preferCSSPageSize: true,
  margin: { top: '18mm', right: '12mm', bottom: '18mm', left: '12mm' },
});

When CSS declares an @page size, decide whether that size or the API’s paper settings should govern the result. Paper dimensions and margins both affect the available content area. The options reference documents these settings, but actual rendered output can depend on the page’s CSS and browser version.

3. How do I set the top, right, bottom, and left margins?

Provide each side inside margin. The values can differ, so you can reserve more space at the top for a header or at the bottom for annotations.

await page.pdf({
  path: 'report.pdf',
  margin: {
    top: '1.25in',
    right: '0.6in',
    bottom: '0.9in',
    left: '0.6in',
  },
});

Each side is optional according to the PDFMargin reference. Setting all four sides explicitly avoids relying on omitted values when consistent page padding is important.

4. Troubleshooting PDF margin problems

Symptom	Likely cause	What to check
No visible whitespace around the page content	The `margin` option is missing or values are too small.	Pass a margin object to the same `page.pdf()` call and set all four sides with explicit units.
Page dimensions do not match the expected paper	The default paper format is Letter, or CSS page dimensions are taking precedence.	Set `format` explicitly. If the document uses CSS `@page`, check `preferCSSPageSize` and the page’s CSS.
The PDF looks different from the browser viewport	PDF generation uses print media styles by default.	Inspect print CSS, or call `page.emulateMediaType('screen')` before `page.pdf()` if screen styling is intended.
Content appears scaled or wraps differently	The content is being fitted to the selected paper size, or the available printable area changed with the margins.	Review `format`, `preferCSSPageSize`, and the four margin values together.
Margin values behave unexpectedly	Values are ambiguous or unsupported by the installed version.	Use strings with explicit units and consult the API reference for the Puppeteer version installed by the project.

The API references describe the accepted options and defaults; they do not guarantee an identical rendered layout for every page, stylesheet, or browser version. Verify the generated PDF in the environment where it will be produced.

5. Performance, reliability, and cost

Margin configuration itself is a small part of PDF generation. In a capture workflow, page loading, scripts, fonts, images, and page length can affect completion time and output size. Use an appropriate navigation readiness condition for the site, and make the page’s paper size, media type, and margins explicit so layout does not depend on defaults. Keep the Puppeteer version consistent across environments and check the matching documentation when upgrading.

Running Puppeteer means operating a browser process and handling its deployment and resource use. If you only need a rendered PDF and do not need to manage browser setup, a screenshot API can be an alternative.

6. Or skip the browser setup

ScreenshotNeo provides a website screenshot API and MCP server. Its PDF endpoint can return a PDF from one GET request; see the ScreenshotNeo documentation for the API options.

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

For an API response that returns a PDF, save the response using a PDF filename and configure the PDF options supported by the API. ScreenshotNeo can remove cookie and consent banners, newsletter popups, and chat widgets before capture; bot checks, blank pages, and failed loads are never billed; and its MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card, and paid plans start at $5 for 3,000. Sign up for free and get 1,000 screenshots a month with no card.

7. FAQ

What happens if I leave the PDF margin option out?

Puppeteer’s PDFOptions reference says the default is undefined, meaning no margins are set.

Can each margin side have a different value?

Yes. Set top, right, bottom, and left independently in the margin object.

Does Puppeteer use print or screen CSS for PDFs?

Print media is used by default. Emulate the screen media type before calling page.pdf() to use screen styles.

Which paper size does Puppeteer use by default?

The documented default is Letter. Choose a format explicitly when the output must use a different paper size.