Recommended Free Tools
iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
Headful mode makes Chrome visible; it does not give Puppeteer a programmatic PDF-download handler. If you want to save the page currently rendered in Chrome as a PDF, use page.pdf(). If you want to retrieve an existing PDF through a website’s download flow, Puppeteer’s current files guide says it does not offer a programmatic way to handle file downloads.
First decide which PDF task you mean
There are two different operations that are easy to confuse:
- Print a rendered web page to a new PDF: Puppeteer supports this with
Page.pdf(). It prints the page content and can write the generated PDF to disk. - Download an existing PDF from a website: A link or button triggers the site to deliver a PDF file. Puppeteer’s current files guide says it does not offer a way to handle file downloads programmatically. Launching a visible browser does not change that documented limitation.
The steps below cover the supported page-to-PDF operation first, then clarify what headful mode does and does not do for an existing file. These details reflect the official Puppeteer documentation available for version 25.12.0; check the documentation for the version and browser you use because APIs and browser mappings can change.
Free tools Windows power users keep installed
One-click scans. No signup required.
Generate a PDF from a page in headful mode
Set headless: false in the launch options to open a visible Chrome window. Puppeteer launches headless by default. The documented chrome-headless-shell mode is selected separately with headless: 'shell'; for regular visible Chrome, use false.
#1 Best Overall
Complete JavaScript example
const puppeteer = require('puppeteer');
(async () => {
const browser = await puppeteer.launch({ headless: false });
try {
const page = await browser.newPage();
await page.goto('https://example.com', { waitUntil: 'networkidle2' });
await page.pdf({ path: 'page.pdf' });
} finally {
await browser.close();
}
})();This navigates to the page, asks Puppeteer to print its rendered content, writes the result to page.pdf, and closes Chrome even if an error occurs. The path is relative to the Node.js process’s working directory. The example’s navigation wait condition is not a guarantee that every site has finished loading all content; choose a readiness condition that suits the page, and add a selector wait or other page-specific logic where needed.
Puppeteer documents Page.pdf() for printing PDFs. By default, PDF generation uses print CSS media, and it waits for fonts by default. To render using screen media instead, call page.emulateMediaType('screen') before page.pdf().
Choose whether to save a file or use PDF bytes
page.pdf() returns a Promise<Uint8Array>. When you provide path, Puppeteer writes the generated PDF there. If you omit path, the API returns the PDF bytes instead of writing a file; your application can then pass those bytes to its own storage or response handling.
const pdfBytes = await page.pdf();
// pdfBytes is a Uint8Array; handle it in your application.Use a path when a file on disk is the desired result. Use returned bytes when the PDF should flow directly into another part of your program. In either case, this creates a PDF from the rendered page; it does not intercept a website’s separate file-download flow.
Rank #2
Set print layout and page selection
Pass PDF options to page.pdf(options) to control paper, orientation, margins, and which pages are included. Puppeteer’s documented defaults and controls are:
| Option | What it controls | Important detail |
|---|---|---|
format |
Paper format | The documented default is Letter. When set, it takes priority over width and height. |
width, height |
Paper dimensions | Use these when specifying dimensions rather than selecting a format. |
margin |
Page margins | Set the margins appropriate to your output. |
landscape |
Page orientation | Set to true for landscape orientation. |
scale |
Scale of the rendered page | Useful for adjusting how content fits on a page. |
pageRanges |
Pages included | Specify a subset of pages when you do not need the entire document. |
printBackground |
Background graphics | Defaults to false; enable it if background colors or images should print. |
preferCSSPageSize |
CSS @page sizing |
Set it when CSS page size should take priority over other sizing choices. |
waitForFonts |
Font readiness | Defaults to true and waits for document.fonts.ready. |
Example with explicit options
await page.pdf({
path: 'report.pdf',
format: 'A4',
landscape: false,
printBackground: true,
preferCSSPageSize: true,
margin: {
top: '12mm',
right: '12mm',
bottom: '12mm',
left: '12mm'
}
});These options give you control over PDF generation, but they do not guarantee that a particular site’s content will paginate as intended. Print styles, page breaks, long tables, and dynamic content can all affect the result. Inspect the output for the target site and adjust its CSS or the PDF options as needed.
Understand what headful mode changes
Headful mode controls whether the Chrome browser window is visible. It can be useful while debugging navigation or observing how a page renders. It is separate from the PDF operation: page.pdf() prints rendered page content, while a website download is a distinct browser file-download flow.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Since Puppeteer v20, its documentation describes Chrome for Testing as supporting both headless and headful modes with the same browser code path. The documentation distinguishes this from the separate chrome-headless-shell program. Consult Puppeteer’s supported browsers guidance for the current Puppeteer-to-browser mapping rather than assuming any installed Chrome version is interchangeable.
When the website already hosts the PDF
If the page has a link such as “Download PDF,” calling page.pdf() will not save the linked file; it will print the page you are viewing. The Puppeteer files guide states: “Currently, Puppeteer does not offer a way to handle file downloads in a programmatic way.” The documented support for uploads is not a download API, and the reviewed documentation does not establish a recommended workaround or a site-independent method to retrieve existing PDFs.
Do not treat headless: false as a workaround. It opens a visible browser, but the official documentation does not say that visibility provides programmatic download management. If your actual requirement is to obtain an existing file, identify a supported retrieval method for the site and verify it against the Puppeteer release and browser version in your application; the PDF-printing API is for a different job.
Troubleshooting generated PDFs
The PDF does not contain the existing file linked on the page
Cause: page.pdf() prints rendered page content; it does not handle the site’s file-download flow. Fix: Treat printing and retrieving a linked PDF as separate tasks. The current files guide does not document a programmatic download handler.
The output does not match the on-screen appearance
Cause: PDF generation uses print CSS media by default. Fix: If the desired output should use screen styles, call await page.emulateMediaType('screen') before generating the PDF. Review the site’s print CSS and page layout as well.
Background colors or images are missing
Cause: printBackground defaults to false. Fix: Set printBackground: true in the PDF options if backgrounds belong in the output.
Content is clipped or paginated unexpectedly
Cause: Paper size, margins, scale, CSS page sizing, and the site’s print styles influence layout. Fix: Select the intended format or dimensions, tune margin and scale, and consider preferCSSPageSize when the site defines CSS @page rules. Check whether a page range is excluding expected pages.
Fonts look incomplete
Cause: The page may not have the fonts ready when content is printed, or the page may not have loaded the intended font resources. Fix: Puppeteer waits for document.fonts.ready by default through waitForFonts: true. If changing that option, account for font readiness explicitly; also verify that the page can load its fonts.
Chrome remains open after an error
Cause: The browser was not closed on the error path. Fix: Put browser work in a try block and call browser.close() in finally, as in the example above.
Best Value
Performance, reliability, and cost considerations
PDF generation requires launching a browser, navigating to the page, waiting for the page state you choose, and rendering the document. Headful mode also opens a visible window, which is useful for observation but is not necessary to make page.pdf() work. Choose navigation and readiness waits based on the site; a generic network-idle condition may not mean that a page’s own dynamic content is complete.
The official documentation reviewed does not provide a universal timing guarantee, a cost figure, or a promise of visual fidelity for arbitrary sites. For repeatable output, control the page state and PDF options, use a version-compatible browser, and inspect generated PDFs for the sites and layouts that matter to your application.
Or skip the browser setup
If the goal is a screenshot rather than a PDF of the rendered page, ScreenshotNeo can return a website screenshot with one GET request. It is a screenshot API, not a replacement for Puppeteer’s PDF-printing method. Its cookie-banner, popup, and chat-widget cleanup can each be turned off; bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and response headers identify the page verdict and billing status. It also provides an MCP server for AI agents, with take_screenshot, get_page_info, and capture_pdf tools.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com -o shot.webpSee the ScreenshotNeo API documentation for request options. The free plan includes 1,000 shots per month with no card; paid plans start at $5 for 3,000 shots. Sign up for 1,000 free screenshots a month with no card.
Frequently Asked Questions
Does Puppeteer’s PDF method return a file or data?
It returns a Promise that resolves to a Uint8Array. Set the path option to have Puppeteer write the generated PDF to disk.
Can Puppeteer generate a PDF without opening a visible browser?
Yes. Puppeteer launches headless by default; headful mode is optional for PDF generation.
Quick Recap
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.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
