Recommended Free Tools
To download multiple files with Puppeteer, configure Chrome’s download policy and a dedicated output directory, trigger independent downloads concurrently, then verify every expected file before using it. The key caveat: Puppeteer’s v25.12.0 Files guide says it does not offer programmatic download handling, while its DownloadBehavior reference documents download configuration—not a stable per-file completion event. So Promise.all can coordinate clicks, but it cannot by itself prove that files have finished downloading.
What Puppeteer does—and does not—provide
There are two separate tasks in browser downloads: allowing Chrome to save files, and detecting when each file is complete. Puppeteer’s Files guide for v25.12.0 states: “Currently, Puppeteer does not offer a way to handle file downloads in a programmatic way.” Its DownloadBehavior reference for v25.12.0 documents a policy and a path. It does not document an event for awaiting the completion of each individual download.
That means there is no universal, version-independent Puppeteer recipe that both starts several downloads and awaits their completion through a documented lifecycle API. You can still automate the workflow: set download behavior where supported, start independent actions concurrently, and use a tested completion check suited to your installed Puppeteer and Chrome versions.
Prepare a deterministic download run
Define what counts as success
Before triggering anything, record which files you expect and how you will identify them. Prefer stable filenames from the page or a known naming pattern. If the site changes names, redirects to generated names, or returns duplicate filenames, define matching rules before the run. Do not infer success merely from the number of click promises that resolved.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →#1 Best Overall
- Read Before You Buy — No Video Output: These adapters support charging and USB 2.0 data transfer, but cannot transmit video signals. Except for standard USB webcams (which use USB data only), they are not compatible with HDMI/DisplayPort cables, video-capable USB-C hubs, or docking stations with video output.
- Convert USB-A Ports to USB-C: Designed to connect USB-C earphones, cables, flash drives, card readers, and other USB-C accessories to standard USB-A ports. Plug-and-play with no drivers or software required.
- Aluminum Alloy Housing: Built with a sturdy aluminum alloy shell that aids in heat dissipation and protects against daily wear and scratches. Designed to maintain a stable and secure connection.
- Compact & Travel-Friendly: The ultra-compact design allows the adapter to stay plugged into your device without blocking adjacent ports or adding bulk, reducing wear and tear on your original USB ports.
- 12-Month Warranty: Backed by a 12-month manufacturer warranty for peace of mind. Designed to meet strict quality control standards for reliable everyday performance.
Use a fresh output directory
Create a unique directory for each run. This separates new outputs from old files and makes it easier to detect missing downloads, duplicate-name suffixes, and partial files. Ensure the process can write to it, and clean it up only after validation and downstream processing have completed.
Set Chrome’s download policy
The v25.12.0 DownloadBehavior reference says downloadPath is required when the policy is allow or allowAndName. The latter saves files using download GUIDs as filenames, so do not expect the server-provided basename to remain intact. Confirm the API shape against the Puppeteer version installed in your project before copying a configuration example: the separate BrowserContextOptions page that exposes a downloadBehavior property is under Puppeteer’s Next/preview documentation.
The example below uses that context option shape, so it is appropriate only when your installed release supports it. It demonstrates concurrent triggering and a filesystem polling pattern; it is not a claim that Puppeteer provides a built-in download-completion handler. Validate the behavior with your exact Puppeteer and Chrome runtime before relying on it in production.
Example: trigger downloads concurrently and check the output
Install Puppeteer in a Node.js project, then save the following as an ES module such as download.mjs. Replace the URL and selectors with those for the page you control. The selectors must identify independent download controls, and the expected names must match the files Chrome actually writes.
Rank #2
- 5-in-1 USB-C Hub: Experience comprehensive connectivity featuring a Power Delivery input, two USB-A 2.0 ports, a USB-A 3.0 port, and an HDMI port. (Note: The USB-C power delivery input port is only for connecting an external wall charger to power your laptop and cannot power peripheral devices.)
- 90W Pass-Through Charging: Achieve optimal charging with 90W pass-through power to your laptop, supported by a total input of 100W, with the hub reserving 10W for operational efficiency. (Note: Wall charger not included.)
- Quick Data Transfers: Accelerate your productivity with rapid data transfers using a high-speed 5Gbps USB 3.0 port and two 480Mbps USB 2.0 ports.
- 4K HDMI Display: Enhance your visual experience with a hub capable of delivering 4K resolution at 30Hz in both mirror and extend modes. Please note that this hub is compatible with MacBook (macOS 12 and newer), Windows 10 and 11, ChromeOS, and laptops equipped with DP Alt Mode and Power Delivery. Note: This device is not compatible with Linux.
- What You Get: Anker USB-C Hub (5-in-1, 4K HDMI), welcome guide, 18-month warranty, and our friendly customer service.
This sample deliberately uses a unique directory and checks for the expected files. It does not treat a fixed delay as proof of completion. The polling check is only appropriate if the target browser writes recognizable files into the configured directory and the filenames are deterministic. Some browsers or download flows use temporary suffixes or GUID filenames, which require adapting the matcher and validation logic.
import puppeteer from 'puppeteer';
import { mkdtemp, readdir, stat } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
const pageUrl = 'https://example.com/reports';
const downloadButtons = ['#download-report-a', '#download-report-b'];
const expectedFiles = ['report-a.csv', 'report-b.csv'];
const timeoutMs = 60_000;
const pollIntervalMs = 300;
const downloadPath = await mkdtemp(join(tmpdir(), 'puppeteer-download-'));
const browser = await puppeteer.launch({ headless: true });
try {
const context = await browser.createBrowserContext({
downloadBehavior: {
policy: 'allow',
downloadPath,
},
});
const page = await context.newPage();
await page.goto(pageUrl, { waitUntil: 'domcontentloaded' });
// Start the independent page actions together. This waits for the click
// actions, not for the browser to finish writing the resulting files.
await Promise.all(
downloadButtons.map((selector) => page.click(selector)),
);
const deadline = Date.now() + timeoutMs;
let missing = expectedFiles;
while (Date.now() < deadline) {
const names = new Set(await readdir(downloadPath));
missing = expectedFiles.filter((name) => !names.has(name));
if (missing.length === 0) {
// Check that expected files are present and non-empty. If the target
// runtime uses temporary download files, also verify those are gone.
const fileStats = await Promise.all(
expectedFiles.map((name) => stat(join(downloadPath, name))),
);
if (fileStats.every((fileStat) => fileStat.isFile() && fileStat.size > 0)) {
break;
}
}
await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
}
if (missing.length > 0) {
throw new Error(`Timed out waiting for: ${missing.join(', ')}`);
}
console.log(`Validated files in ${downloadPath}`);
} finally {
await browser.close();
}The example’s file-presence and non-empty checks are intentionally modest. For important data, validate file contents too—for example, parse a CSV and check expected columns or records. A file can exist and still be truncated, invalid, or unrelated to the requested download. If filenames are unpredictable, inspect the actual output directory and implement a target-specific way to map completed files to expected downloads.
Start actions in parallel without confusing that with completion
Use Promise.all when the page permits independent controls to be activated at once. It waits until all supplied promises resolve, but in this example those promises represent click actions only. A click resolving is not evidence that a network request succeeded, that Chrome accepted the download, or that the file was fully written.
Parallel triggering may also be inappropriate for pages that allow only one active export, require one job to finish before another can start, or apply server-side throttling. In those cases, follow the site’s workflow and limit concurrency. The official sources cited here establish no general maximum number of concurrent downloads or numeric speed advantage; both depend on the target page, browser, and server.
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 →Rank #3
- Sleek 7-in-1 USB-C Hub: Features an HDMI port, two USB-A 3.0 ports, and a USB-C data port, each providing 5Gbps transfer speeds. It also includes a USB-C PD input port for charging up to 100W and dual SD and TF card slots, all in a compact design.
- Flawless 4K@60Hz Video with HDMI: Delivers exceptional clarity and smoothness with its 4K@60Hz HDMI port, making it ideal for high-definition presentations and entertainment. (Note: Only the HDMI port supports video projection; the USB-C port is for data transfer only.)
- Double Up on Efficiency: The two USB-A 3.0 ports and a USB-C port support a fast 5Gbps data rate, significantly boosting your transfer speeds and improving productivity.
- Fast and Reliable 85W Charging: Offers high-capacity, speedy charging for laptops up to 85W, so you spend less time tethered to an outlet and more time being productive.
- What You Get: Anker USB-C Hub (7-in-1), welcome guide, 18-month warranty, and our friendly customer service.
Wait for and validate each expected output
Because the reviewed Puppeteer guide does not document a native programmatic download lifecycle handler, completion detection must be tested against the browser/runtime and site you use. Filesystem polling is one option when output names and temporary-file behavior are known. A robust check should distinguish at least these outcomes:
- Missing: an expected file never appeared before the timeout.
- Partial or in progress: a temporary download file remains, or file size is still changing.
- Present but invalid: the final path exists, but content validation fails.
- Complete: the expected file is present, no relevant partial-download marker remains, and any required content checks pass.
Do not use a fixed sleep as a completion guarantee. A delay can be too short on a slow response and waste time on a fast one. A timeout bounds the wait; it does not make an incomplete file complete. When implementing polling, check for the target browser’s temporary-file conventions and avoid treating a transient final-looking name as proof without validating stability or content.
Authentication, contexts, and filename edge cases
Authenticated downloads
Trigger authenticated downloads through the page and browser context that has the required site state, then verify that the target server actually returns the intended file. Puppeteer documents that browser contexts isolate storage such as cookies and local storage. The v25.12.0 BrowserContext reference also says a popup remains in the context of its opener. Those facts help explain which browser state a page uses, but do not guarantee that every server-side download flow will authenticate as expected.
Chrome’s extension downloads documentation says HTTP(S) downloads initiated through that extension API include cookies set for the URL hostname. That statement is specific to the extension API and should not be treated as a general guarantee for every Puppeteer-driven download path. Confirm authentication against your actual flow, especially when a click opens a popup, navigates to a signed URL, or starts a request through page JavaScript.
Rank #4
- Dual Converters, Infinite Potential：Includes 2× USB C male to USB A female adapters and 2× USB A male to USB C female adapters. Perfect for a wide range of uses—tablets with Bluetooth keyboards, expand USB ports on macbook, and more. Two different converters for all your daily needs
- Next-Level 10Gbps & 3A Charging: No more slow 480Mbps, this usb to usb c adapter has a transfer speed of up to 10Gbps, allowing you to do more transferring in less time. This usb adapter fits both USB A and USB C charger, supporting up to 3A fast charging
- Upgraded Exquisite Craftsmanship: With an aluminum alloy housing and metal connector, the usbc to usb adapter is extremely durable and sturdy. Rigorously tested to withstand more than 10,000 times of plugging and unplugging, ensuring long-lasting performance
- Broad Compatible: The usb c to usb adapter widely supports all USB C/ USB A devices like laptops, tablets, cellphones, car chargers, and phone chargers. Such as compatible with MacBook Pro/Air 2023/2022, Thunderbolt 4/3 Devices,Apple MagSafe Watch 9/8/7/SE/Ultra, iPad Pro 2022/2021, Samsung Galaxy S23/S20/S10, and iPhone 17/16/15 Pro. Plug and play
- Please Note: To reach 10Gbps speed, keep the cable under 3.3 ft. For USB A Male to USB C adapters, try flipping the USB C connector. USB C Male to USB A adapters support bidirectional 10Gbps transfer within 3.3 ft
Duplicate names, redirects, and generated filenames
If two downloads have the same basename, Chrome may rename one to avoid overwriting, or a GUID naming policy may produce opaque names. Redirects and server-generated filenames can also make a link’s visible text differ from the saved name. Use a fresh directory, inspect the actual names produced, and map outputs to expected items using information your workflow can reliably observe. Do not silently accept “two files appeared” as proof that the two intended files arrived.
Alternative when explicit download states are required
Chrome’s chrome.downloads extension API can initiate and monitor downloads in an extension context. It exposes download IDs and states including in_progress, interrupted, and complete. This offers explicit lifecycle visibility, but it is a Chrome extension API requiring the extension context and permission; it is not a drop-in Node.js Puppeteer method.
Choose that route only if an extension is part of your architecture. If you stay with Puppeteer, keep download configuration, trigger concurrency, and completion validation as distinct steps, and test the exact runtime behavior you deploy.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Troubleshooting common failures
No file appears
- Confirm the page action really starts a download rather than opening a preview or a new tab.
- Check that the installed Puppeteer release accepts the download behavior configuration you are using; do not assume a Next/preview option exists in a stable release.
- Verify the configured path exists and is writable by the process.
- Check whether the page requires authentication, a prior user interaction, or a completed export job before the download control works.
The script times out with a partial file
- Increase the timeout only if the target workload legitimately needs longer; retain a bounded wait.
- Check for slow server responses, large files, network interruptions, and temporary-download markers.
- Do not process the file until it is stable and passes the validation appropriate to its format.
The wrong file or filename is detected
- Use a unique directory so previous-run files cannot satisfy the current run’s check.
- Account for duplicate names, Chrome renaming, server-provided names, redirects, and
allowAndNameGUID filenames. - Match based on reliable output characteristics rather than assuming link labels equal saved filenames.
Only one download starts, or requests fail under concurrency
- Check whether the site serializes exports or throttles simultaneous requests.
- Try a lower concurrency level or the site’s own export-job sequence; parallel clicks are not always supported by the page.
- Report and retry failures per file rather than treating one rejected promise as evidence that every download failed.
Or skip the browser setup
If the job is to capture pages as images or PDFs rather than download arbitrary files from a site’s own controls, ScreenshotNeo offers a one-request screenshot API and an MCP server for AI agents. A cURL example is:
Best Value
- 5-in-1 Connectivity: Equipped with a 4K HDMI port, a 5 Gbps USB-C data port, two 5 Gbps USB-A ports, and a USB C 100W PD-IN port. Note: The USB C 100W PD-IN port supports only charging and does not support data transfer devices such as headphones or speakers.
- Powerful Pass-Through Charging: Supports up to 85W pass-through charging so you can power up your laptop while you use the hub. Note: Pass-through charging requires a charger (not included). Note: To achieve full power for iPad, we recommend using a 45W wall charger.
- Transfer Files in Seconds: Move files to and from your laptop at speeds of up to 5 Gbps via the USB-C and USB-A data ports. Note: The USB C 5Gbps Data port does not support video output.
- HD Display: Connect to the HDMI port to stream or mirror content to an external monitor in resolutions of up to 4K@30Hz. Note: The USB-C ports do not support video output.
- What You Get: Anker 332 USB-C Hub (5-in-1), welcome guide, our worry-free 18-month warranty, and friendly customer service.
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 documentation for API details. Cookie banners, popups, and chat widgets are removed before the shot; bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots, and 1,000 screenshots a month are free with no card; paid plans start at $5 for 3,000. Sign up free for ScreenshotNeo.
Frequently Asked Questions
Does Puppeteer have a built-in event that tells me each download is complete?
The v25.12.0 Files guide says Puppeteer does not offer programmatic download handling, and the DownloadBehavior reference documents configuration rather than an individual-download completion event. Verify any version-specific alternative against your installed release.
Can I run several downloads at once with one Puppeteer page?
You can trigger independent page actions concurrently when the site supports it, but concurrent clicks do not establish that the resulting downloads completed. Validate the expected outputs separately.
Should I use a new browser context for every download?
Not by default. Contexts isolate browser storage, but the documentation does not say that separate contexts are required for parallel transfers or that they solve download tracking.
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.
