The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →To control files downloaded by a page in Puppeteer, set downloadBehavior in the browser’s launch or connect options. Use policy: 'allow' and an absolute downloadPath to permit downloads into a chosen directory. This is a runtime setting for page downloads—not the browser download that may happen while installing Puppeteer.
Configure downloads when launching Puppeteer
The current Puppeteer API reference is for version 25.12.0. Its DownloadBehavior option accepts a policy and, for permitted downloads, a destination path. LaunchOptions extends ConnectOptions, so you can pass the same option when launching a browser or connecting through the common options interface.
As an Amazon Associate I earn from qualifying purchases.
import puppeteer from 'puppeteer';
const browser = await puppeteer.launch({
downloadBehavior: {
policy: 'allow',
downloadPath: '/absolute/path/to/downloads',
},
});
try {
const page = await browser.newPage();
await page.goto('https://example.com');
// Trigger a page download here, such as by clicking a download link.
} finally {
await browser.close();
}Replace the example path with a directory valid for the machine running Puppeteer. The process must be able to write there. Puppeteer’s API reference says the path is required for allow and allowAndName; it does not establish that Puppeteer creates the directory automatically, so create it yourself if needed. See the DownloadBehavior interface and ConnectOptions reference.
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 reinstallChoose the right download policy
| Policy | Effect | Path requirement |
|---|---|---|
deny |
Blocks downloads. | Not required by the API definition. |
allow |
Permits downloads using the chosen 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. | Not required by the API definition. |
The API describes allowAndName as naming all files according to their download GUIDs. Choose it only when GUID-based filenames are suitable for your workflow; it is not the option for preserving a human-readable filename as the primary name. Source: Puppeteer DownloadBehavior interface.
#1 Best Overall
Set a custom download directory
Set downloadPath to the path where the browser process should save permitted files. For example, retain policy: 'allow' and replace the sample path:
downloadBehavior: {
policy: 'allow',
downloadPath: '/tmp/puppeteer-downloads',
}Use a path appropriate to the host: an absolute POSIX path on Linux or macOS, or a valid absolute Windows path on Windows. Make sure the directory exists and is writable by the account running Node.js. The API requires the path for allow and allowAndName, but does not specify directory-creation or permission-handling behavior.
Rank #2
Configure behavior when connecting to a browser
downloadBehavior is part of ConnectOptions, which is also the base of LaunchOptions. That lets you supply it in the common options interface when connecting, as well as when launching. The exact connection setup depends on how the browser was started; ensure the installed Puppeteer version and browser/protocol combination support the behavior you need. The reviewed stable API reference does not establish a universal compatibility matrix.
const browser = await puppeteer.connect({
browserWSEndpoint: 'ws://127.0.0.1:9222/devtools/browser/…',
downloadBehavior: {
policy: 'allow',
downloadPath: '/absolute/path/to/downloads',
},
});Use a real WebSocket endpoint for your browser rather than the illustrative endpoint above. See ConnectOptions.
Rank #3
How do I configure browser downloads in Puppeteer?
- Choose the destination directory on the host that runs the browser.
- Create the directory if it does not already exist, and confirm the Node.js process can write to it.
- Pass
downloadBehavior: { policy: 'allow', downloadPath: '/absolute/path/to/downloads' }in the launch or connect options. - Trigger the page’s download, then inspect the chosen directory and handle the resulting file in your automation.
The option configures browser handling of downloads; it does not itself trigger a download or provide a separate wait-for-file-complete API.
Do not confuse page downloads with browser installation
Puppeteer’s downloadBehavior controls page-triggered file downloads at runtime. Installing the puppeteer package is a different workflow: that package downloads a compatible browser during installation, while puppeteer-core does not download Chrome when installed. If a package manager blocks install scripts and the required browser is missing, Puppeteer documents npx puppeteer browsers install as a manual browser-installation remedy. That command installs a browser; it does not set a page download directory. See the installation guide.
Troubleshooting download behavior
- Downloads are not permitted: Check that the policy is
alloworallowAndName, rather thandenyordefault. - The API rejects a missing path: Supply
downloadPathfor eitheralloworallowAndName. - No file appears at the destination: Confirm the page actually triggered a download, the path is valid for the browser host, and the browser process has write access. Also verify that you are inspecting the host where the browser is running.
- The downloaded filename is unexpected: If using
allowAndName, filenames follow download GUIDs. Useallowif that naming behavior is not wanted. - Puppeteer reports that its browser is missing: This is an installation issue, not a download-directory setting. Consult the installation guide and, where relevant, use
npx puppeteer browsers install. - Behavior differs after connecting or across browsers: Check the installed Puppeteer version and exact browser/protocol combination. The stable API documentation does not provide a complete compatibility matrix.
Or skip the browser setup
If the goal is a screenshot or PDF of a web page rather than downloading a file through page automation, ScreenshotNeo provides a website screenshot API and MCP server. One GET request can return a PNG, JPEG, WebP, or PDF. Its clean-shot steps can accept consent banners and remove known consent platforms, newsletter popups, and chat widgets; each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers report the page verdict and billing status. Its MCP server includes tools for AI agents to take screenshots, inspect page information, and capture PDFs.
Example cURL request (replace YOUR_API_KEY with your key):
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 request options. The free plan includes 1,000 shots per month with no card; paid plans start at $5 for 3,000. Sign up for ScreenshotNeo’s free plan.
Quick Recap
Best Value
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.
