To stop headless Chrome from downloading images, intercept network requests in Puppeteer and abort requests whose resource type is image. Continue every other request so stylesheets, fonts, scripts, and page data still load. Headless mode itself does not block images.
Block image requests in Puppeteer
Enable interception before navigating, then check each request’s resource type. Abort image requests and continue all others:
const page = await browser.newPage();
await page.setRequestInterception(true);
page.on('request', request => {
if (request.resourceType() === 'image') {
return request.abort();
}
return request.continue();
});
await page.goto('https://example.com');This is the image-only adaptation of Chrome’s documented Puppeteer interception pattern: the browser can modify or stop requests before they are issued. Check the API documentation for the Puppeteer version installed in your project, since the cited Chrome example is older and does not establish a current version number.
What this changes
- Requests that Puppeteer identifies as images are aborted before their content is downloaded.
- Other requests continue, preserving the page’s ordinary loading behavior for resources such as CSS, JavaScript, fonts, and media.
- The page may show empty image areas or broken-image indicators. The page’s own scripts may also react to failed image requests.
Set the interception listener before page.goto(); otherwise, requests made during navigation could start before the policy is in place. If your code already has a request listener, combine the filtering logic with it rather than registering competing handlers that may both try to resolve the same request.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Fix the driver behind crashes, sound loss and screen glitches3Repair Windows errors before they cause bigger problems#1 Best Overall
Image-only filtering or a resource allowlist?
| Approach | What continues | Trade-off |
|---|---|---|
Abort only image requests |
All requests except those classified as images | Closest match when the goal is specifically to avoid image downloads. |
| Allow only selected resource types | Only the types you name, for example document, script, xhr, and fetch |
Also blocks unlisted resources, which can include stylesheets, fonts, and media; page appearance or behavior may change. |
Chrome’s server-side-rendering example uses the allowlist approach. Choose it only when you intend to suppress those additional resource types. Neither approach has a documented fixed speedup: avoiding image downloads can reduce bandwidth and work, but the effect depends on the page and workload.
Why Headless Chrome still loads images
Headless describes running a browser without a visible user interface; it is not an image-blocking setting. Chrome’s current unified Headless mode shares code with Chrome, so resource filtering belongs in your automation’s network policy. See Chrome’s Headless mode documentation.
Chrome 112 introduced unified Headless. Starting with Chrome 132.0.6793.0, the older Headless implementation is available as a separate chrome-headless-shell binary. These are version markers for the browser modes, not a requirement to change modes to block images.
Troubleshooting
Images still appear
- Confirm interception is enabled and the listener is registered before navigation.
- Check that the listener is attached to the same Puppeteer page being navigated.
- Verify the request classification in your installed Puppeteer environment; the filter applies to requests reported as resource type
image. - If page code inserts images after navigation, ensure the listener remains active for the page’s lifetime.
The page looks unstyled or stops working
Check whether your code uses a resource allowlist. An allowlist that omits stylesheet, fonts, or other needed types blocks them too. For image suppression alone, use the narrow request.resourceType() === 'image' condition and continue all other requests.
Navigation reports failed requests
Aborted image requests are intentionally unsuccessful. If your workflow treats any failed request as a page failure, distinguish expected image aborts from document or script failures in your own request/error handling.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Or skip the browser setup
If you need a screenshot rather than a custom Puppeteer workflow, ScreenshotNeo is a website screenshot API and MCP server. Its capture process accepts cookie and consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets before the shot; each of those steps can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and the response identifies the page verdict and billing status in headers. Its MCP server offers screenshot and page-information tools for AI agents.
One GET request returns an image or PDF. Example cURL call (replace the target URL and use your API key):
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. Plans include 1,000 screenshots a month free with no card; paid plans start at $5 for 3,000. Sign up for the free plan.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Quick Recap
Sources
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.
