Puppeteer’s DownloadPolicy controls files that a page tries to download while the browser is running. Choose deny to block downloads, allow to save them in a configured directory, allowAndName to save them under download GUIDs, or default to defer to Chrome’s default behavior when available (otherwise downloads are denied). For either allowing policy, configure downloadPath.
What does Puppeteer DownloadPolicy control?
DownloadPolicy is the runtime browser setting for whether pages controlled by Puppeteer may initiate file downloads. The four documented values in Puppeteer 25.12.0 are deny, allow, allowAndName, and default. This setting is about page downloads, not whether Puppeteer downloads a browser during installation.
As an Amazon Associate I earn from qualifying purchases.
Which download policy should you use?
| Policy | Effect | Path and filename behavior | Use it when |
|---|---|---|---|
deny |
Denies all download requests. | No download directory is needed. | Your automation should not save files. |
allow |
Allows download requests. | Set downloadPath to choose the save directory. Browser filename behavior is used. |
You need downloads in a known directory and want the browser’s filename behavior. |
allowAndName |
Allows download requests. | Requires downloadPath; files are named with download GUIDs, not the website’s suggested filenames. |
Your workflow can track GUIDs and does not depend on the original filenames. |
default |
Uses Chrome’s default behavior if available; otherwise denies downloads. | Delegates the outcome to the browser’s available default behavior. | You specifically want browser-default behavior rather than an explicit allow or deny. |
The policy meanings and path requirements are documented in the Puppeteer DownloadBehavior API and DownloadPolicy type (Puppeteer 25.12.0).
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Configure the policy in Puppeteer
When launching a locally managed Puppeteer browser, pass the download behavior through the launch options. Set a path for either policy that allows downloads:
#1 Best Overall
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 the page's download here.
} finally {
await browser.close();
}Replace the example path with a directory that exists and is writable by the process running Chromium. To block page downloads, use policy: 'deny' and omit the path. To accept GUID filenames, change the policy to 'allowAndName'; a configured path remains required. The optional downloadBehavior on ConnectOptions is documented as setting the behavior for the connected context; consult the ConnectOptions API for the Puppeteer version in use.
What changes at the Chrome DevTools Protocol level?
The underlying Chrome DevTools Protocol method is Browser.setDownloadBehavior. It supports a browserContextId; if omitted, the behavior applies to the default browser context. Its eventsEnabled parameter defaults to false. The protocol reference marks this method experimental, so its status and details may change across Chromium releases. See the Chrome DevTools Protocol Browser reference.
Runtime downloads are not Puppeteer installation downloads
Changing DownloadPolicy does not control the browser binary Puppeteer obtains during package installation. The installation guide says the puppeteer package normally downloads a compatible browser, while puppeteer-core does not download Chrome and is intended for setups where you manage the browser or connect to a remote one. If install scripts are blocked, the guide gives npx puppeteer browsers install as a manual installation command. These are installation concerns, separate from files downloaded by pages at runtime; see the Puppeteer installation guide.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Or skip the browser setup
If your goal is a screenshot rather than browser automation, ScreenshotNeo provides a website screenshot API and MCP server. A single request returns an image or PDF; its clean-shot steps can accept consent banners and remove known consent platforms, newsletter popups, and chat widgets before capture. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and responses identify the page verdict and billing status. Its MCP server offers screenshot and PDF tools for AI agents.
cURL example, with the API details in the ScreenshotNeo documentation:
Rank #3
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpScreenshotNeo’s 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.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Frequently Asked Questions
Does allowAndName preserve the filename suggested by a website?
No. It names downloads using their download GUIDs.
Does DownloadPolicy configure Chrome’s installation download?
No. It governs downloads initiated by pages in a running browser, not Puppeteer’s browser installation.
Windows 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 reinstallOutdated 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 matchQuick 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.
