Main Website
Web Scraping
Web Scraping
Updated on
May 21, 2024

Bypass or Solve CAPTCHA in Puppeteer: Working Examples

When it comes to web scraping, automation and testing, Puppeteer is an incredibly powerful tool. However, one of the most significant obstacles that developers face when using Puppeteer is the infamous CAPTCHA (Completely Automated Public Turing test to tell Computers and Humans Apart). CAPTCHAs are designed to prevent bots and automated scripts from accessing websites, but they can be a major roadblock for legitimate use cases like scraping, automation and testing.

In this article, we’ll delve into the world of CAPTCHAs and explore ways to bypass or solve them when using Puppeteer. We’ll discuss the reasons why you might encounter CAPTCHA errors when using Puppeteer for scraping and other use cases, and provide solutions to overcome these challenges.

Why do you run into CAPTCHA errors when using Puppeteer?

Encountering CAPTCHA errors when utilizing Puppeteer for various tasks, including scraping, automation, and testing, can be a hurdle to overcome. Understanding the underlying reasons behind these errors is crucial for effectively addressing them and ensuring smooth execution of Puppeteer scripts. Several factors contribute to the occurrence of CAPTCHA errors in Puppeteer workflows:

Bot detection mechanisms

Websites employ sophisticated bot detection mechanisms to distinguish between genuine human users and automated scripts like those executed by Puppeteer. These mechanisms are designed to safeguard websites against malicious activities such as scraping, spamming, and unauthorized access. When Puppeteer interacts with websites, its automated behavior can inadvertently trigger these bot detection mechanisms, leading to the presentation of CAPTCHA challenges. For example, if a Puppeteer script sends requests very often, goes to the same web pages in a regular way, or acts like a robot, the website might think it is suspicious activity. The website may flag the activity as suspicious and prompt the user to complete CAPTCHA challenges for verification.

JavaScript execution

Puppeteer operates by controlling headless instances of Chrome or Chromium browsers, allowing for the execution of JavaScript code like a regular browser. However, some websites implement CAPTCHA mechanisms that rely on JavaScript execution to detect and verify user interactions. When Puppeteer executes JavaScript on these websites, it may trigger CAPTCHA challenges designed to verify the authenticity of user actions. Additionally, websites may employ JavaScript-based bot detection techniques to analyze user behavior and identify automated scripts, leading to the presentation of CAPTCHA challenges.

CAPTCHA providers

Many websites integrate CAPTCHA solutions provided by services such as Google reCAPTCHA or custom CAPTCHA implementations. These services utilize various techniques, including image recognition, text-based challenges, and behavioral analysis, to verify user authenticity and prevent automated access. When Puppeteer interacts with websites that utilize CAPTCHA providers, it may encounter CAPTCHA challenges as a result of the website's reliance on these services to differentiate between human users and automated scripts.

Rate limiting and suspicious activity

Websites may impose rate limits or flag suspicious activity, such as excessive requests from a single IP address or user agent. Puppeteer's automated browsing behavior, particularly when scraping large volumes of data or executing rapid actions, can trigger these protective measures, leading to the presentation of CAPTCHA challenges as a means of verifying user authenticity and mitigating potential abuse.

Dynamic content and anti-scraping measures

Many websites employ dynamic content generation and anti-scraping measures to deter automated access to their resources. These measures may include dynamically generated form tokens, hidden HTML elements, or traps to block bots. Puppeteer's inability to accurately interpret and interact with dynamically changing elements can lead to CAPTCHA errors when websites detect inconsistencies or suspicious behavior indicative of automated access.

Bypassing CAPTCHA with puppeteer-extra-plugin-recaptcha

In Puppeteer automation, handling CAPTCHA challenges effectively is crucial for seamless workflow. One effective method involves leveraging the puppeteer-extra-plugin-recaptcha plugin, an extension of Puppeteer Extra library, specifically designed to solve Google reCAPTCHA challenges automatically. Here’s how to implement this solution:

Installation and setup

To begin, ensure that you have Puppeteer and Puppeteer Extra installed in your project. Additionally, install the puppeteer-extra-plugin-recaptcha plugin using npm:

npm install puppeteer puppeteer-extra puppeteer-extra-plugin-recaptcha

By installing the puppeteer-extra-plugin-recaptcha plugin, you equip Puppeteer with the capability to handle Google reCAPTCHA challenges seamlessly. This plugin extends Puppeteer's functionality, enabling it to interact with and solve reCAPTCHA challenges encountered during automation.

Integration of the puppeteer-extra-plugin-recaptcha

Integrating the plugin into your Puppeteer script is a straightforward process. Simply require the puppeteer-extra-plugin-recaptcha plugin and add it to the list of plugins used by Puppeteer using puppeteer.use() method. This step ensures that Puppeteer is equipped with the necessary functionality to handle reCAPTCHA challenges.

const puppeteer = require('puppeteer-extra');
const RecaptchaPlugin = require('puppeteer-extra-plugin-recaptcha');

// Set up the plugin
    provider: {
      id: '2captcha',
      token: 'YOUR_2CAPTCHA_API_KEY',
    visualFeedback: true,

Here, you will need to replace YOUR_2CAPTCHA_API_KEY with your actual 2Captcha API key.

Automating CAPTCHA solving

Once the plugin is integrated, you can automate CAPTCHA solving within your Puppeteer script with ease. After navigating to the webpage containing reCAPTCHA, simply call the page.solveRecaptchas() method. This function interacts with the reCAPTCHA challenge, solving it automatically without requiring manual intervention.

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

  // Navigate to the page with the reCAPTCHA
  await page.goto('');

  // Solve the reCAPTCHA
  await page.solveRecaptchas();

  // Continue with your script...

  await browser.close();

Bypassing CAPTCHA with puppeteer-extra-plugin-stealth

puppeteer-extra-plugin-stealth is a versatile tool designed to enhance Puppeteer's stealth capabilities, allowing users to bypass CAPTCHA challenges effortlessly. By mimicking human-like behavior and evading bot detection mechanisms, this plugin enables seamless automation of tasks without interruption from CAPTCHA prompts. Here’s how to use puppeteer-extra-plugin-stealth plugin to overcome CAPTCHA challenges:

Installation and setup

Install Puppeteer, puppeteer-extra, and puppeteer-extra-plugin-stealth as dependencies in your project using npm. This plugin, puppeteer-extra-plugin-stealth, enhances Puppeteer's stealth capabilities to mimic human-like behavior, thereby bypassing bot detection mechanisms like CAPTCHA challenges.

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

Integration of puppeteer-extra-plugin-stealth

Integrate the puppeteer-extra-plugin-stealth plugin into your Puppeteer script by requiring puppeteer-extra, puppeteer, and the plugin itself. The plugin is added to puppeteer-extra using the use() method, ensuring that its stealth features are applied during browser initialization.

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

// Add the Stealth plugin

Automating CAPTCHA solving

With the plugin integrated, the below Puppeteer script navigates to the webpage containing the CAPTCHA challenge. puppeteer-extra-plugin-stealth works behind the scenes to enhance Puppeteer's stealth capabilities, reducing the likelihood of triggering CAPTCHA challenges while interacting with the webpage. After navigating to the page, Puppeteer can continue with its automation tasks as usual, such as scraping data or automating user actions.

(async () => {
  const browser = await puppeteerExtra.launch();
  const page = await browser.newPage();
  // Navigate to the page with CAPTCHA
  await page.goto('');

  // Continue with your Puppeteer actions
  // For example, scraping data or automating tasks
  await browser.close();

Bypassing CAPTCHA with random-useragent

Randomizing user agents using the random-useragent package can significantly enhance Puppeteer scripts' stealth capabilities, thereby aiding in bypassing CAPTCHA challenges. By dynamically assigning user agents, Puppeteer can mimic human-like behavior more effectively, reducing the risk of triggering CAPTCHA prompts during automation tasks. 

Installation and setup

Ensure that you have Node.js installed on your system. Install the random-useragent package using npm. This package provides functionality to generate random user-agents or retrieve valid user-agents for Puppeteer.

npm install random-useragent

Integration into Puppeteer script

Require the random-useragent package in your Puppeteer script. In the following snippet, the package is used to set a random user-agent for the Puppeteer browser instance. This ensures that each browser instance created by Puppeteer has a unique user-agent, helping to mimic human-like behavior and evade bot detection mechanisms, including CAPTCHA challenges.

const puppeteer = require('puppeteer');
const randomUseragent = require('random-useragent');

(async () => {
  const browser = await puppeteer.launch({
    // Set a random user-agent for the browser instance
    args: [`--user-agent=${randomUseragent.getRandom()}`]
  const page = await browser.newPage();
  // Continue with your Puppeteer actions
  // For example, scraping data or automating tasks

  await browser.close();

Best practices for avoiding CAPTCHA in Puppeteer

In this section, we’ll discuss best practices and tips for avoiding CAPTCHA challenges effectively, including strategies for minimizing CAPTCHA encounters, optimizing code performance, and maintaining compliance with website terms of service.

Minimizing CAPTCHA encounters

The first step in handling CAPTCHA challenges is to minimize their occurrence. Here are some best practices for minimizing CAPTCHA encounters:

  1. Use a Rotating Pool of IP Addresses: CAPTCHA challenges are often triggered by repeated requests from the same IP address. Using a rotating pool of IP addresses can help you avoid this trigger.
  2. Use a Delay Between Requests: CAPTCHA challenges are also often triggered by rapid-fire requests. Adding a delay between requests can help you avoid this trigger.
  3. Use a Real Browser Profile: Some websites use browser fingerprinting to identify automated requests. Using a real browser profile can help you avoid this trigger.
  4. Use a Headless Browser: Some websites check for visual signs to identify automated requests. Using a headless browser can help you avoid this trigger.

Optimizing code performance

Optimizing code performance is important for handling CAPTCHA challenges effectively. Here are some best practices for optimizing code performance:

  1. Use Asynchronous Requests: Asynchronous requests allow you to make multiple requests simultaneously, which can improve performance and reduce the likelihood of triggering CAPTCHA challenges.
  2. Use Caching: Caching can help you reduce the number of requests you need to make, which can improve performance and reduce the likelihood of triggering CAPTCHA challenges.
  3. Use Rate Limiting: Rate limiting can help you avoid making too many requests in a short period of time, which can improve performance and reduce the likelihood of triggering CAPTCHA challenges.

Maintaining compliance with website terms of service

Maintaining compliance with website terms of service is important for handling CAPTCHA challenges effectively. Here are some best practices for maintaining compliance:

  1. Read and Understand the Terms of Service: Before scraping or automating any website, make sure you read and understand the website's terms of service.
  2. Respect Robots.txt Files: Robots.txt files are used to indicate which pages on a website can be scraped or crawled. Make sure you respect these files and only scrape or crawl pages that are allowed.
  3. Use a User Agent: Using a user agent can help you identify yourself to the website and indicate that you are a legitimate user.
  4. Use a Proxy: Using a proxy can help you avoid IP bans and maintain compliance with website terms of service.

Wrapping up: Solving CAPTCHA challenges with Puppeteer

In this article, we've explored strategies for bypassing CAPTCHA challenges in Puppeteer automation. Understanding the reasons behind CAPTCHA errors, such as bot detection mechanisms, is crucial. By leveraging tools like random-useragent for randomizing user agents, puppeteer-extra-plugin-stealth for stealth capabilities, and puppeteer-extra-plugin-recaptcha for automated CAPTCHA solving, developers can enhance the reliability of their Puppeteer scripts. These techniques streamline automation workflows, minimize interruptions, and improve overall efficiency.

Guide to Puppeteer Extra: Best Plugins For Scraping Ranked

User-Agent in Puppeteer: Random & Custom Methods Explained

Proxy in Pyppeteer: Learn the Perfect Scraping Setup