Use page.pdf(options) to control Puppeteer’s PDF paper size, margins, orientation, print styling, page ranges and output. It uses print CSS by default. This guide follows the Puppeteer 25.12.0 API reference; check your installed Puppeteer version and protocol backend when relying on a particular option.
Generate a PDF with Puppeteer
Call page.pdf() after navigating to the page. The API returns the PDF data; set path in the options if you also want Puppeteer to write a file. This example uses documented defaults for paper selection and appearance, and explicitly sets a path:
const puppeteer = require('puppeteer');
(async () => {
const browser = await puppeteer.launch();
try {
const page = await browser.newPage();
await page.goto('https://example.com', { waitUntil: 'networkidle0' });
await page.pdf({
path: 'page.pdf',
format: 'A4',
printBackground: true,
margin: { top: '15mm', right: '15mm', bottom: '15mm', left: '15mm' }
});
} finally {
await browser.close();
}
})();Replace the example URL with the page you control or are authorized to capture. The API details below are from the Puppeteer PDFOptions reference.
Choose who controls the PDF page size
There are three practical approaches to geometry. The format option defaults to letter and takes precedence over explicit width and height. To use custom dimensions, omit format. To let the page’s CSS define its own paper dimensions, use preferCSSPageSize: true.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →#1 Best Overall
| Approach | Set | Effect |
|---|---|---|
| Named paper | format: 'A4' (or another supported paper format) |
Uses the named format. If format is present, it wins over width and height. |
| Explicit dimensions | width and/or height |
Accepts numbers or strings with units. Omit format if the dimensions should determine the paper. |
| CSS page geometry | preferCSSPageSize: true |
Prioritizes the size declared by CSS @page over API paper dimensions. If false, Puppeteer scales content to fit the selected paper size. |
For example, a page can declare its print geometry in CSS:
@page {
size: A4 landscape;
margin: 12mm;
}Then use preferCSSPageSize: true if that CSS size should take priority. The option’s default is false; a CSS declaration alone does not change that default.
Set orientation and margins
landscape defaults to false. Set it to true for landscape output. The optional margin object accepts top, bottom, left and right, each as a number or a string with a unit. Margins are unset by default.
Rank #2
- HTML CSS Design and Build Web Sites
- Comes with secure packaging
- It can be a gift option
await page.pdf({
format: 'A4',
landscape: true,
margin: {
top: '12mm',
right: '10mm',
bottom: '12mm',
left: '10mm'
}
});Choose one place to own page margins when using CSS @page and API margins together. Verify the rendered result for your page and Puppeteer version rather than assuming the two declarations combine in the way you intend.
Recommended Free Tools
Control print media, backgrounds and colors
page.pdf() uses print media by default, so print-specific CSS applies. To render screen-media styles instead, call page.emulateMediaType('screen') before generating the PDF. This changes the media query context; it does not by itself guarantee that every screen color or background appears in the PDF.
await page.emulateMediaType('screen');
await page.pdf({
path: 'screen-styled.pdf',
printBackground: true
});printBackgrounddefaults tofalse. Set it totrueto include background graphics.omitBackgrounddefaults tofalse. Set it totrueto hide the default white background and allow a transparent PDF background.- For CSS-controlled print color fidelity, use
-webkit-print-color-adjust: exactwhere appropriate. Puppeteer normally adjusts colors for printing.
Media selection, background inclusion and color adjustment are separate concerns: choose each according to the page’s CSS and the output you need. See the Puppeteer Page class reference for documented PDF media and color behavior.
Rank #3
Select pages and adjust scale
pageRanges selects which PDF pages to include. Its empty-string default means all pages. Use comma-separated page numbers and ranges, such as '1-5, 8, 11-13'. The scale option defaults to 1 and accepts values from 0.1 through 2.
await page.pdf({
path: 'selected-pages.pdf',
pageRanges: '1-5, 8, 11-13',
scale: 0.9
});Page ranges refer to the PDF’s generated pages, not source-document page labels. If the document has fewer pages than a requested range, inspect the resulting output and correct the range for the actual page count.
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Clear out junk files and repair common Windows errors3Fix the driver behind crashes, sound loss and screen glitchesAdd headers and footers
Header and footer rendering is off by default. Set displayHeaderFooter: true and provide HTML through headerTemplate and/or footerTemplate. Puppeteer documents special classes for injected date, title, URL, page number and total pages.
Rank #4
- Brand: Wiley
- Set of 2 Volumes
- A handy two-book set that uniquely combines related technologies Highly visual format and accessible language makes these books highly effective learning tools Perfect for beginning web designers and front-end developers
await page.pdf({
path: 'numbered.pdf',
displayHeaderFooter: true,
headerTemplate: '<div style="font-size:8px;width:100%;text-align:center"><span class="title"></span></div>',
footerTemplate: '<div style="font-size:8px;width:100%;text-align:center"><span class="pageNumber"></span> / <span class="totalPages"></span></div>',
margin: { top: '20mm', bottom: '20mm' }
});Reserve enough page margin for template content, and use the documented class names when you want Puppeteer to insert those values. The option reference documents the template constraints and special classes; confirm layout against your page and installed version.
Choose output, timeout and font behavior
pathis optional. When set, Puppeteer writes the PDF there; relative paths resolve from the current working directory. Without it, the PDF is not written to disk, thoughpage.pdf()still returns PDF data.timeoutis measured in milliseconds and defaults to30,000. Set it to0to disable the PDF operation timeout. The page’s default timeout can also be changed withPage.setDefaultTimeout().waitForFontsdefaults totrueand waits fordocument.fonts.ready. The documentation notes that a background page might needPage.bringToFront()for fonts to load.
Set an explicit timeout only when the default is unsuitable for your workload. Disabling it removes this timeout as a stopping condition, so your own job orchestration should still handle operations that do not finish.
Know the less routine PDF flags
outlinerequests a document outline and is marked experimental; its documented default isfalse.taggedrequests a tagged PDF and is marked experimental; its documented default istrue.
Because both are documented as experimental, check the behavior of your installed Puppeteer and downstream PDF readers before depending on them for production requirements.
Check your protocol backend: WebDriver BiDi
The general PDFOptions API reference covers more options than Puppeteer’s WebDriver BiDi support page. For BiDi, the documented Page.pdf() and Page.createPDFStream() subset is format, height, landscape, margin, pageRanges, printBackground, scale and width. Do not assume fields outside this set work with BiDi. If your implementation needs header/footer templates, preferCSSPageSize, tagged output or another unlisted field, verify the backend’s support before designing around it. See Puppeteer WebDriver BiDi support.
Troubleshoot common PDF output problems
- Unexpected paper dimensions: Check whether
formatis set, since it overrideswidthandheight. If CSS should decide the size, setpreferCSSPageSize: true. - Backgrounds are missing: Set
printBackground: true. If the page also relies on screen-specific styles, emulate screen media beforepage.pdf(). - Colors differ from the browser view: PDF generation uses print media by default and normally adjusts colors for printing. Review print CSS and, if exact CSS colors are intended, consider
-webkit-print-color-adjust: exact. - Text or web fonts are not ready:
waitForFontsis enabled by default. Check font loading and, for a background page, whether bringing it to the foreground withPage.bringToFront()is needed. - PDF generation times out: The PDF timeout defaults to 30,000 milliseconds. Check whether the page is ready, then adjust
timeoutor the page default timeout if the job legitimately needs longer. - An option appears ignored under BiDi: Compare it with the documented BiDi subset above. The general API’s availability does not establish BiDi support.
- Header or footer is absent: Enable
displayHeaderFooter; templates alone do not enable it.
Or skip the browser setup
If you need a website screenshot rather than a Puppeteer-generated PDF, ScreenshotNeo provides a screenshot API and MCP server. Its one-call API can return a screenshot or PDF:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com -o page.pdfSee the ScreenshotNeo API documentation for output options. ScreenshotNeo removes cookie banners, popups and chat widgets before the shot; 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 free for ScreenshotNeo.
Frequently Asked Questions
Which Puppeteer PDF media type is used by default?
Print media. Call page.emulateMediaType('screen') before page.pdf() to use screen media.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallQuick Recap
What is the default paper format for Puppeteer PDFs?
The documented default is letter.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
