A Complete Guide to Puppeteer Real Browser in 2025

In this guide, you will learn:

• What Puppeteer Real Browser is
• How it works to avoid bot detection and solve CAPTCHAs
• How it compares to vanilla Puppeteer
• How to use it against real-world bot detection systems
• Its main alternatives
• Its key limitations
• A better approach to anti-bot browser automation

Let’s dive in!

What Is Puppeteer Real Browser?

Puppeteer Real Browser is a JavaScript library that makes the browser controlled by Puppeteer behave more like a real user. That reduces bot detection on WAF services like Cloudflare and similar. It also supports automatic CAPTCHA solving, including Cloudflare Turnstile.

The library extends Puppeteer with custom configurations while supporting proxies and all other features of vanilla Puppeteer. It is open-source—with over 1k stars on GitHub, is available on npm as puppeteer-real-browser, and supports Docker for deployment.

Note: In February 2025, the author of the library, mdervisaygan, announced that the project would no longer receive updates. This does not mean that Puppeteer Real Browser is necessarily dead, as community members may continue its development through a fork.

How Does Puppeteer Real Browser Work?

If you have ever worked with browser automation tools like Puppeteer, Playwright, or Selenium, you know that browsers controlled by these tools can be detected by anti-bot systems. That is especially true when operating in headless mode—even when using the best headless browsers.

Blocks happen because automation libraries configure browsers in a way that makes them easier to control. Anti-bot solutions look for these configurations and “leaks” to determine whether requests come from a real human using a regular browser or an automated bot.

Puppeteer Real Browser addresses that issue using Rebrowser, a collection of patches for Puppeteer and Playwright designed to prevent automation detection.

Rebrowser modifies puppeteer-core directly, patching the browser runtime to remove bot-like traces left by Puppeteer. Those changes make the browser appear more like a real user session, reducing the chances of being blocked by anti-bot systems.

However, WAFs like Cloudflare may still present one-click CAPTCHAs:

In that case, Puppeteer Real Browser relies on ghost-cursor to interact with CAPTCHAs just like a real user would. That is a JavaScript library that generates human-like mouse movements in Puppeteer or any 2D plane.

The problem is that Puppeteer mouse events are often detected as synthetic due to unnatural cursor behavior. Puppeteer Real Browser fixes that issue by improving how .screenX and .screenY values are handled, making mouse movements appear more natural. This helps trick Cloudflare Turnstile, reCAPTCHA, and other one-click CAPTCHAs into thinking the interaction is from a real human user.

The library also includes:

• Puppeteer Extra: To enable extension via plugins
• Xvfb: To handle virtual browser displays, ideal for headless environments.

In short, Puppeteer Real Browser combines different enhancements to create a stealthy, high-fidelity automation tool that mimics human users while avoiding detection.

Puppeteer Real Browser vs Puppeteer

Below is puppeteer vs puppeteer-real-browser summary table to compare the two technologies:

How to Use Puppeteer Real Browser to Bypass CATPCHAs

To demonstrate the capabilities of Puppeteer Real Browser, we will test it against Scraping Course’s Anti-Bot Challenge page:

This Cloudflare-protected page features a Turnstile one-click CAPTCHA. In this step-by-step section, we will show how to use Puppeteer Real Browser to solve it.

For an alternative approach, check out our guide on bypassing CAPTCHAs in Puppeteer. What is essential to know is that a standard Puppeteer script attempting to access that page will always encounter the Turnstile CAPTCHA and get blocked.

As you are about to see, Puppeteer Real Browser is an effective solution for bypassing Cloudflare and similar anti-bot protections!

Step #1: Install puppeteer-real-browser

We will assume you already have a Node.js project set up. If not, you can create one using npm init.

Now, navigate to your project folder and install puppeteer-real-browser with:

npm install puppeteer-real-browser

On Linux, you also need to install xvfb as a system-level dependency. For Debian-based systems, install it with:

sudo apt-get install xvfb

Great! You are now ready to use Puppeteer Real Browser to bypass CAPTCHAs.

Step #2: Initial Setup

In your JavaScript script, import connect from Puppeteer Real Browser:

const { connect } = require("puppeteer-real-browser");

The connect() function allows you to establish a connection to the modified browser engine within an async function:

(async () => {
  const { browser, page } = await connect({
    headless: false,
    turnstile: true,
  });

  // scraping logic...

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

Just like in vanilla Puppeteer, you need to call browser.close() to release resources.

The connect() function in Puppeteer Real Browser accepts the following parameters:

• headless: Default is false. Other values like "new", true, and "shell" can be used, but false is the most stable.
• args: Additional Chromium flags can be passed as a string array. See supported flags.
• customConfig: Puppeteer Real Browser is initialized using chrome-launcher. Any options you pass here will be added as direct initialization arguments. You can use this to set userDataDir or a custom Chrome path (chromePath).
• turnstile: If true, Puppeteer Real Browser automatically clicks Cloudflare Turnstile CAPTCHAs.
• connectOption: Options sent when connecting to Chromium using puppeteer.connect().
• disableXvfb: On Linux, when headless: false, a virtual display (xvfb) is used to run the browser. Set it to true to disable this and see the actual browser window.
• ignoreAllFlags: If true, all default initialization arguments are overridden, including the “Let’s get started” page that appears on first load.
• plugins: An array of Puppeteer Extra plugins. Find out more in the official documentation.

All other options supported by the above function come from the Puppeteer connect() method.

Since we want to bypass Cloudflare, the key setting in this example is turnstile to true.

Step #3: Connect to the Target Page

Use the goto() function from the Puppeteer API to navigate to the target page:

await page.goto("https://www.scrapingcourse.com/antibot-challenge");

Since turnstile is set to true, Puppeteer Real Browser will automatically wait for the Cloudflare Turnstile CAPTCHA to load and attempt to solve it.

Step #4: Wait for CAPTCHA Solving

If you open the target page in incognito mode and manually solve the CAPTCHA, you will get the following result:

Inspect the message using DevTools, and you will see:

Notice that the message element can be selected using the #challenge-info CSS selector.

Now, define a custom function to wait for the page DOM to change:

function delay(timeout) {
  return new Promise((resolve) => {
    setTimeout(resolve, timeout);
  });
}

This function is necessary because puppeteer-real-browser does not provide a built-in callback for CAPTCHA resolution. As we expect Puppeteer Real Browser to successfully bypass the CAPTCHA, the page DOM will update accordingly, and you need to wait for these changes.

Thus, you can use delay() to wait for a set period of time to allow the page to fully update, as below:

await delay(10000);

Then, wait for the target message element to be on the page:

await page.waitForSelector("#challenge-info", { timeout: 5000 });

Then, retrieve and print its content:

const challengeInfo = await page.$eval(
  "#challenge-info",
  (el) => el.textContent.trim()
);
console.log(`Page message: "${challengeInfo}"`);

If everything works as expected, the script should output:

Page message: "You bypassed the Antibot challenge! :D"

Step #5: Put It All Together

Below is your final Puppeteer Real Browser script:

const { connect } = require("puppeteer-real-browser");

// custom function to implement a hard wait
function delay(timeout) {
  return new Promise((resolve) => {
    setTimeout(resolve, timeout);
  });
}

(async () => {
  // connect to the controlled browser
  const { browser, page } = await connect({
    headless: false,
    turnstile: true, // enable Turnstile CAPTCHA handling
    connectOption: {
      defaultViewport: null, // make the viewport as large as the browser window
    },
    args: ["--start-maximized"], // start the browser in a maximized window
  });

  // navigate to the challenge page
  await page.goto("https://www.scrapingcourse.com/antibot-challenge", {
    waitUntil: "networkidle2", // Wait for the page to be fully loaded and idle
  });

  // wait up to 10 seconds for the CAPTCHA to be solved
  await delay(10000);

  // wait up to 5 seconds for the challenge info element to appear
  await page.waitForSelector("#challenge-info", { timeout: 5000 });

  // retrieve and print the challenge info text
  const challengeInfo = await page.$eval(
    "#challenge-info",
    (el) => el.textContent.trim()
  );
  console.log(`Page message: "${challengeInfo}"`);

  // close the browser and release its resources
  await browser.close();
})();

Launch the above code, and it will open a browser behaving as follows:

The script visits a Cloudflare-protected page, automatically solves the CAPTCHA, and then reaches the destination page, extracting data from it.

As desired, the script will produce this result in the terminal:

Page message: "You bypassed the Antibot challenge! :D"

Fantastic! The Cloudflare CAPTCHA has been automatically solved.

Alternatives to puppeteer-real-browser

Since puppeteer-real-browser is no longer maintained, it is worth exploring alternatives that offer similar features, such as:

• Puppeteer Stealth: A plugin for Puppeteer Extra that applies various evasions to make automation less detectable. It modifies browser fingerprints, disables WebRTC leaks, and mimics human-like behavior to bypass anti-bot measures.
• Playwright Stealth: A Playwright Extra plugin that integrates the same stealth techniques similar to Puppeteer Stealth. It patches browser APIs to prevent fingerprinting leaks.
• SeleniumBase: A fully-featured Selenium-based automation framework with built-in anti-bot detection features. It includes bot evasion techniques, user-agent spoofing, CAPTCHA handling, and other tools to help Selenium scripts bypass bot protection.
• undetected-chromedriver: A modified ChromeDriver version that helps Selenium scripts bypass bot detection. It removes automation flags, obfuscates WebDriver properties, and ensures the browser behaves more like a human-operated session.

Puppeteer Real Browser Limitations

Puppeteer Real Browser is a powerful anti-bot browser automation tool, but it does come with a few drawbacks. The author is transparent about these constraints, providing clear insights into its limitations.

The main limitations are:

• No longer maintained: As of February 2025, the original author announced that the library will no longer receive updates. Future improvements will depend on community contributions rather than active development.
• Not 100% undetectable: While it reduces bot detection, advanced anti-bot systems may still flag automated traffic.
• Requires additional configuration: Users may need to fine-tune proxies, headers, and other settings for optimal stealth and functionality.
• Cannot access functions in window object: This occurs due to the browser runtime being closed by Rebrowser. A workaround is injecting JavaScript into the page using puppeteer-intercept-and-modify-requests, or using Chrome plugins.
• Dependent on external libraries: The library relies on third-party projects like Rebrowser, Puppeteer Extra, and ghost-cursor, which could change or be discontinued.
• Issues with reCAPTCHA: reCAPTCHA v3 requires an active Google session to be passed. Even with an undetectable browser, automation attempts without a valid session are likely to be flagged.

Seamless Anti-Bot Browser Automation

The drawbacks mentioned above might discourage you from considering Puppeteer Real Browser altogether. While you could try one of its alternatives, you are likely to encounter similar challenges.

What matters is that most anti-bot browser automation libraries focus on patching browsers, not the browser automation library itself. Although minor modifications to the core of those libraries may be needed, most of the effort goes into patching browser engines to avoid detection leaks.

Now, imagine being able to utilize vanilla browser automation libraries like Playwright, Puppeteer, and Selenium—relying on their updates and stable APIs—to control a cloud-based, scalable browser specifically designed for web scraping. That is exactly the experience provided by Bright Data’s Scraping Browser!

Scraping Browser comes with a built-in website unlocking feature that handles blocking for you automatically. It integrates seamlessly with a proxy network of over 72 million IPs, works efficiently in the cloud, and includes an integrated CAPTCHA solver.

Optimized browsers for scraping are the real solution to achieving anti-bot browser automation!

Conclusion

In this article, you understood how to deal with bot detection in Puppeteer using Puppeteer Real Browser. This library provides a patched version of puppeteer-core for web scraping without getting blocked.

The problem is that puppeteer-real-browser is no longer maintained. So, while it may work today, it might not work tomorrow as anti-bot solutions keep evolving.

The issue does not lie with Puppeteer’s API for controlling the browser, but with the browsers themselves. The solution is a cloud-based, always-updated, scalable browser with built-in anti-bot bypass functionality, such as Scraping Browser!

Bright Data’s Scraping Browser is a highly scalable cloud browser that works with Puppeteer, Selenium, Playwright, and others. It handles browser fingerprinting, CAPTCHA resolution, and automated retries for you.

Plus, it automatically rotates the exit IP with each request, thanks to a global proxy network that includes:

• Datacenter proxies – Over 770,000 datacenter IPs.
• Residential proxies – Over 150M residential IPs in more than 195 countries.
• ISP proxies – Over 700,000 ISP IPs.
• Mobile proxies – Over 7M mobile IPs.

Create a free Bright Data account today to try out our scraping browser or test our proxies.