Block images with Puppeteer

If you’ve ever worked with Puppeteer—the Node.js library for controlling headless Chrome or Chromium browsers—you’ve probably come across situations where you need to block certain types of requests. Perhaps you’re scraping a website and want to speed things up by not loading images, or you need to block pesky third-party scripts for more reliable testing. Whatever the case, blocking resources is actually a lot easier than you might think.

Below, we’ll walk through a few helpful strategies to block images or other unwanted requests.

Why Block Certain Requests?

When you’re automating browsers, every resource—CSS, images, fonts, trackers—takes time to load. By blocking requests to unnecessary assets, you can:

• Speed up scraping or testing: Images, videos, and ads can significantly slow down page load times. Blocking them often results in a snappier, more efficient experience.
• Reduce bandwidth costs: If you’re running large-scale scraping campaigns or executing many tests, blocking extraneous resources can cut down on bandwidth usage.
• Improve Reliability: Eliminating extraneous scripts and trackers can make your page behavior more predictable, which is useful for testing and automation.

Setting Up a Basic Puppeteer Script

Before diving into request blocking, let’s assume you have a basic Puppeteer setup. Here’s a skeleton code snippet for starting a browser, creating a page, and navigating to a URL:

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch();
  const page = await browser.newPage();

  await page.goto('https://example.com');

  // ... we’ll add request blocking logic here ...

  await browser.close();
})();

How to Block Images

One of the simplest use cases is blocking images. With Puppeteer, you can intercept and modify requests as they’re being made. To achieve this, you’ll rely on the page.setRequestInterception(true) method and then listen for the request event on the page.

await page.setRequestInterception(true);

page.on('request', (req) => {
  const resourceType = req.resourceType();
  if (resourceType === 'image') {
    req.abort();
  } else {
    req.continue();
  }
});

await page.goto('https://example.com', { waitUntil: 'networkidle2' });

In this snippet, we turn on request interception before navigating. Then for each request, we check if it’s an image. If it is, we abort it, effectively blocking it from loading. Otherwise, we let the request continue as normal.

How to Block Specific File Types or Domains

What if you need to block more than just images? Maybe you want to block all CSS, or perhaps there’s a pesky analytics script you’d like to cut out. No problem! Just modify the interception logic.

await page.setRequestInterception(true);

page.on('request', (req) => {
  const url = req.url();

  // Block any .css files
  if (url.endsWith('.css')) {
    req.abort();
    return;
  }

  // Block requests to a specific domain
  if (url.includes('tracking-service.com')) {
    req.abort();
    return;
  }

  // Otherwise, let it go
  req.continue();
});

await page.goto('https://example.com', { waitUntil: 'networkidle2' });

This code checks the URL of each request and then aborts it if it matches certain criteria. By extending this logic, you can selectively block fonts, scripts, or any other resources you deem unnecessary.

Using a Predefined List of Blocked Resource Types

If you want to streamline your code even further, you could maintain a list of resource types that you’d like to block and then dynamically abort them. For instance:

const blockedResourceTypes = ['image', 'stylesheet', 'font'];

await page.setRequestInterception(true);

page.on('request', (req) => {
  if (blockedResourceTypes.includes(req.resourceType())) {
    req.abort();
  } else {
    req.continue();
  }
});

await page.goto('https://example.com', { waitUntil: 'networkidle2' });

This approach makes it easy to configure your blocking behavior in one place.

Wrapping Up

Blocking images or other resources with Puppeteer is a practical skill that can significantly enhance the efficiency of your automation, scraping, or testing workflows. By making use of page.setRequestInterception() and listening for the request event, you can finely tune which assets load—saving you time, bandwidth, and headaches.

Whether you’re just trying to speed up a single page load or preparing a full-fledged web scraping pipeline, these methods will help keep your Puppeteer runs lean, mean, and under control. Happy coding!