How to configure Puppeteer Stealth to bypass anti-bot defenses

Websites have learned how to detect bots. Cloudflare, anti-spam systems and scripts are figuring out Puppeteer if not configured correctly. The result? Bans, captchas, and an inability to collect data. This article will show you how to enable Stealth mode in Puppeteer to make the bot look like a normal user and bypass the defenses.

Puppeteer's Stealth mode disguises the bot as a real user: it adds browser fingerprints, simulates mouse movement and hides traces of automation. In this article, we'll figure it out:

• How to install and activate Puppeteer Stealth.
• What plugins and settings are needed to bypass anti-bot protections.
• How to test the work and make sure you are not blocked.

You will learn how to configure Puppeteer so that it bypasses complex defenses and scripts work without interruptions.

Install Puppeteer and activate Stealth mode

To set up Puppeteer Stealth, you need to install the library, plug in the puppeteer-extra-plugin-stealth plugin and configure the startup settings. It's simple.

Install Puppeteer and packages

Open a CMD terminal in Windows and enter commands to install Puppeteer and additional plugins:

npm install puppeteer puppeteer-extra puppeteer-extra puppeteer-extra-plugin-stealth

• puppeteer is the core library for Chrome.
• puppeteer-extra is an extension for plugin integration.
• puppeteer-extra-plugin-stealth is a plugin that hides signs of automation.

Puppeteer in the base version gives itself away: it passes headers like HeadlessChrome and leaves traces that are easy to detect. The Stealth plugin solves this problem.

Connect the Stealth

Create an index.js file and configure the plugin connection. Here is a sample code:

const puppeteer = require('puppeteer-extra');

const StealthPlugin = require('puppeteer-extra-plugin-stealth');

// Connecting the Stealth plug-in

puppeteer.use(StealthPlugin());

(async () => {

    const browser = await puppeteer.launch({ headless: true });

    const page = await browser.newPage();

    // Go to the website for the test

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

    await page.screenshot({ path: 'result.png' });

    console.log('The test is complete. The screenshot is saved.');

    await browser.close();

})();

This code will start the browser in Stealth mode and show how much your bot is masquerading as a normal user.

Configure additional startup parameters

To make the bot look even more believable, add browser startup parameters. For example:

const browser = await puppeteer.launch({

    headless: true,

    args: [

        '--no-sandbox',

        '--disable-setuid-sandbox',

        '--disable-dev-shm-usage',

        '--disable-accelerated-2d-canvas',

        '--disable-gpu'

    ]

});

These settings reduce system load and help bypass some protections.

Options like --no-sandbox and --disable-gpu make the browser faster and eliminate potential conflicts with servers.

Check operation on secure sites

After customization, you need to test Puppeteer. Here are some sites where you can check if the cloaking works:

• bot.sannysoft.com - tests bot behavior.
• whatismybrowser.com - shows what your browser looks like for the site.
• httpbin.org/headers - tests the headers you send.

Configuring Puppeteer Stealth with a proxy

Without a proxy, working with Puppeteer is limited to one IP. If you send too many requests, your IP will be banned. Connecting a proxy solves this problem: requests are sent from different addresses. This is how your work is masked.

Choosing the right proxy

Before connecting a proxy you need to choose which type is suitable for your task:

• Server proxies - provide high speed and stability, useful for mass parsing.
• Mobile proxies - help to bypass anti-bot defenses, as they use real IP addresses of mobile operators.

Connecting a proxy in Puppeteer

Simple proxy connections are made via the --proxy-server argument in the browser settings. Here is a sample code:

const puppeteer = require('puppeteer-extra');

const StealthPlugin = require('puppeteer-extra-plugin-stealth');

puppeteer.use(StealthPlugin());

(async () => {

    const browser = await puppeteer.launch({

        headless: true,

        args: ['--proxy-server=http://username:password@proxy_address:port']

    });

    const page = await browser.newPage();

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

    await page.screenshot({ path: 'proxy-test.png' });

    console.log('The proxy request is complete. The screenshot is saved.');

    await browser.close();

})();

In --proxy-server substitute the proxy address, login and password (if required). For example: http://user:pass@192.168.1.1:8080.

Proxy rotation for parsing

To bypass IP limits, you need to change proxies on each request. This is done using a proxy pool. Here is a sample code for rotation:

const proxyList = [

    'http://user1:pass1@proxy1_address:port',

    'http://user2:pass2@proxy2_address:port',

    'http://user3:pass3@proxy3_address:port'

];

const getRandomProxy = () => proxyList[Math.floor(Math.random() * proxyList.length)];

(async () => {

    for (let i = 0; i < 5; i++) {

        const proxy = getRandomProxy();

        const browser = await puppeteer.launch({

            headless: true,

            args: [`--proxy-server=${proxy}`]

        });

        const page = await browser.newPage();

        await page.goto('https://httpbin.org/ip');

        console.log(`The request is made via proxy: ${proxy}`);

        await browser.close();

    }

})();

The script selects a random proxy from the list before each request, which prevents blocking and distributes the load.

Proxy stability testing

Before using it, be sure to check if the proxy works:

• Load several pages in a row through one proxy to make sure it is stable.
• Check the connection speed - too slow proxies can slow down the whole process.
• Make sure the proxy is suitable for the target region. For example, if the data is only available to US users, use US IPs.

Puppeteer Stealth testing and bug fixing

After setting up Puppeteer Stealth with a proxy, it is important to make sure that everything works correctly. Errors can manifest themselves in various forms: from access denials to unexpected browser behavior. This stage of testing will help to identify and eliminate such problems so that your scripts work stably.

Verification of masking via test sites

The easiest way to make sure that Stealth mode is configured correctly is to use test sites that detect bots:

• bot.sannysoft.com - the site checks browser behavior against a real user.
• whatismybrowser.com - shows information about your browser, including version, fingerprint, and automation traces.
• httpbin.org/headers - returns HTTP request headers, allowing you to check what data is being sent.

Sample code to check at bot.sannysoft.com:

const puppeteer = require('puppeteer-extra');

const StealthPlugin = require('puppeteer-extra-plugin-stealth');

puppeteer.use(StealthPlugin());

(async () => {

    const browser = await puppeteer.launch({ headless: true });

    const page = await browser.newPage();

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

    await page.screenshot({ path: 'stealth-test.png' });

    console.log('The test is complete. The screenshot has been saved.');

    await browser.close();

})();

After testing and bug fixing, you will get a fully customized tool capable of bypassing anti-bot systems and proxy blocking. In the next section, we will summarize the results and give additional tips on optimizing Puppeteer Stealth.