To control files downloaded by a page in Puppeteer, pass downloadBehavior when launching or connecting to the browser. Set policy: 'allow' and an appropriate downloadPath to permit downloads to a chosen directory. This runtime setting is separate from installing Puppeteer’s browser binary.
Configure page downloads with downloadBehavior
The Puppeteer 25.12.0 API documents downloadBehavior in the common browser options. For a launched browser, use:
import puppeteer from 'puppeteer';
const browser = await puppeteer.launch({
downloadBehavior: {
policy: 'allow',
downloadPath: '/absolute/path/to/downloads',
},
});Replace the example path with a directory appropriate for the machine running Puppeteer. The process must have permission to write there. The API requires downloadPath for the allow policy; the reference does not specify whether Puppeteer creates a missing directory, so create and verify the directory yourself rather than relying on automatic creation. See the DownloadBehavior interface and ConnectOptions.
LaunchOptions extends ConnectOptions, so downloadBehavior is available through the shared options interface when launching and when connecting. The precise browser and protocol support can vary; confirm behavior for your installed Puppeteer version and browser if you depend on a particular context or connection setup.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
#1 Best Overall
Choose a download policy
The documented policies determine whether page-triggered downloads are blocked, permitted to a path, or left to browser defaults.
| Policy | Effect | Path requirement |
|---|---|---|
deny |
Blocks downloads. | Not required by the documented policy definition. |
allow |
Permits downloads to the configured destination. | downloadPath is required. |
allowAndName |
Permits downloads and names files according to their download GUIDs. | downloadPath is required. |
default |
Uses the browser’s default behavior, if available. | No path requirement is stated. |
Use allow when you want files saved under their normal names in a chosen directory. Choose allowAndName only if GUID-based filenames suit your workflow; those names may not match the original filenames. The interface and policy details are in Puppeteer’s DownloadBehavior reference.
Rank #2
Set a download path when connecting
Because ConnectOptions includes downloadBehavior, the same setting can be supplied to the browser connection options:
const browser = await puppeteer.connect({
browserWSEndpoint: 'ws://127.0.0.1:9222/devtools/browser/…',
downloadBehavior: {
policy: 'allow',
downloadPath: '/absolute/path/to/downloads',
},
});Use the WebSocket endpoint for the browser you are connecting to, and make sure the path is meaningful and writable in the environment where that browser runs. A remote browser may not share the filesystem layout of the Node.js process. The options are documented in ConnectOptions; do not assume all browser/protocol combinations handle downloads identically.
Rank #3
Do not confuse runtime downloads with browser installation
downloadBehavior controls downloads initiated by pages after a browser is running. It does not download or install Chrome or another browser for Puppeteer.
The puppeteer package downloads a compatible browser during installation, while puppeteer-core does not download Chrome when installed. If an install process blocked package scripts and the required browser is missing, Puppeteer documents this manual installation command:
npx puppeteer browsers installThat command installs a browser binary; it does not set the destination for page-triggered downloads. See the Puppeteer installation guide.
Troubleshoot common download problems
- The download is blocked. Check that your policy is not
deny. To permit downloads to a selected directory, useallowand providedownloadPath. - Puppeteer reports a missing path or downloads do not land where expected. Confirm the path is supplied for
alloworallowAndName, is appropriate for the browser host, and is writable by the browser process. Create the directory yourself if needed; automatic directory creation is not specified in the API reference. - Files have unexpected names. With
allowAndName, Puppeteer names files using their download GUIDs. Useallowif you need ordinary download filenames. - The browser itself is missing. This is an installation problem, not a runtime download-policy problem. Check whether the package installation obtained its browser; the installation guide documents
npx puppeteer browsers installas a manual remedy. - Behavior differs between environments. Verify the installed Puppeteer version, browser, connection method, and protocol. The API references do not establish a complete browser/protocol compatibility matrix.
Or skip the browser setup
If the task is to capture a webpage as an image or PDF rather than automate a page’s file download, ScreenshotNeo provides a screenshot API and MCP server. One GET request can return a PNG, JPEG, WebP, or PDF. For example, save a page capture with cURL:
Free tools Windows power users keep installed
One-click scans. No signup required.
Best Value
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for the request options. It removes supported cookie and consent banners, newsletter popups, and chat widgets before capture; bot checks, blank pages, failed loads, timeouts, and cache hits are not billed. Its MCP server lets AI agents take screenshots. 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 required.
Frequently Asked Questions
Which Puppeteer version do these API names describe?
The referenced API documentation identifies Puppeteer 25.12.0. Check the documentation for your installed version before relying on version-specific behavior.
Does Puppeteer create the download directory automatically?
The API reference does not specify directory-creation behavior. Create the destination directory and ensure the browser process can write to it.
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.
Recommended Free Tools
