--- title: "A Complete Guide to Puppeteer Real Browser in 2026" slug: puppeteer-real-browser date: 2025-06-10T12:08:27+00:00 modified: 2026-04-29T05:36:21+00:00 permalink: https://brightdata.com/blog/web-data/puppeteer-real-browser type: blog --- [ Blog ](https://brightdata.com/blog "Blog") / [Web Data](https://brightdata.com/blog/web-data) [Web Data](https://brightdata.com/blog/web-data) # A Complete Guide to Puppeteer Real Browser in 2026 Explore how Puppeteer Real Browser helps bypass anti-bot systems and solve CAPTCHAs for web scraping in 2026, plus key alternatives and limitations. 11 min read [ ](https://brightdata.com/blog/authors/antonello-zanini) [Antonello Zanini Technical Writer ](https://brightdata.com/blog/authors/antonello-zanini) ![Guide to Puppeteer Real Browser blog image](https://media.brightdata.com/2025/06/Guide-to-Puppeteer-Real-Browser-blog-image.png) 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](https://github.com/ZFC-Digital/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](https://www.cloudflare.com/application-services/products/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`](https://www.npmjs.com/package/puppeteer-real-browser), and supports Docker for deployment. **Note**: In February 2026, the author of the library, [mdervisaygan](https://github.com/ZFC-Digital/puppeteer-real-browser/commits?author=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](/blog/web-data/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](/blog/how-tos/what-is-a-scraping-bot). Puppeteer Real Browser addresses that issue using [Rebrowser](https://github.com/rebrowser/rebrowser-patches), a collection of patches for Puppeteer and Playwright designed to prevent automation detection. Rebrowser modifies [`puppeteer-core`](https://www.npmjs.com/package/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](/blog/web-data/bypass-cloudflare-for-web-scraping): In that case, Puppeteer Real Browser relies on [`ghost-cursor`](https://github.com/Xetera/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](https://hackernoon.com/elevate-your-scraping-project-with-puppeteer-extra): To enable extension via plugins - [Xvfb](https://www.x.org/archive/X11R7.7/doc/man/man1/Xvfb.1.xhtml): 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: **Puppeteer****Puppeteer Real Browser****GitHub stars**1k stars89.7k stars**npm library**`puppeteer``puppeteer-real-browser`**npm downloads**~3.6M weekly downloads~10k weekly downloads**`puppeteer-core` version**Standard `puppeteer-core`Patched `rebrowser-puppeteer-core` to remove automation traces**Anti-bot detection**Easily detected by advanced bot protectionDesigned to evade bot detection systems (Cloudflare, Akamai, etc.)**API**DefaultSame Puppeteer API with additional extensions**Proxy support**Supports proxiesSupports proxies**CAPTCHA handling**No built-in CAPTCHA solvingSupports one-click CAPTCHA solving (e.g., Cloudflare Turnstile, reCAPTCHA)**Plugin support**No native plugin supportIntegrates with `puppeteer-extra` for plugin support**Maintenance and updates**Actively maintained by GoogleDiscontinued by the author (Feb 2026), but may continue via community## 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](https://www.scrapingcourse.com/antibot-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](/blog/web-data/bypass-captchas-with-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](/blog/web-data/bypass-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`](https://docs.npmjs.com/cli/v11/commands/npm-init). Now, navigate to your project folder and install puppeteer-real-browser with: ```none npm install puppeteer-real-browser ``` On Linux, you also need to install [`xvfb`](https://linux.die.net/man/1/xvfb) as a system-level dependency. For Debian-based systems, install it with: ```none 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: ```none const { connect } = require("puppeteer-real-browser"); ``` The `connect()` function allows you to establish a connection to the modified browser engine within an async function: ```none (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](https://github.com/GoogleChrome/chrome-launcher/blob/main/docs/chrome-flags-for-tools.md). - **`customConfig`**: Puppeteer Real Browser is initialized using [`chrome-launcher`](https://github.com/GoogleChrome/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](https://github.com/berstend/puppeteer-extra/tree/master/packages/puppeteer-extra). All other options supported by the above function come from the Puppeteer [`connect()`](https://pptr.dev/api/puppeteer.connectoptions) 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: ```none 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: ```none 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: ```none await delay(10000); ``` Then, wait for the target message element to be on the page: ```none await page.waitForSelector("#challenge-info", { timeout: 5000 }); ``` Then, retrieve and print its content: ```none 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: ```none Page message: "You bypassed the Antibot challenge! :D" ``` ### Step #5: Put It All Together Below is your final Puppeteer Real Browser script: ```none 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: ```none 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**](/blog/how-tos/avoid-getting-blocked-with-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**](/blog/how-tos/avoid-bot-detection-with-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**](/blog/web-data/web-scraping-with-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**](/blog/web-data/web-scraping-with-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 2026, 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](https://github.com/niieani/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](https://stackoverflow.com/questions/52546045/how-to-pass-recaptcha-v3). ## 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](/products/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 400M+ monthly IPs, works efficiently in the cloud, and includes an integrated [CAPTCHA solver](/products/web-unlocker/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](/products/scraping-browser)! Bright Data’s Scraping Browser is a highly scalable cloud browser that works with [Puppeteer](/products/scraping-browser/puppeteer), [Selenium](/products/scraping-browser/selenium), [Playwright](/products/scraping-browser/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](/proxy-types/datacenter-proxies) – 1,300,000+ datacenter IPs. - [Residential proxies](/proxy-types/residential-proxies) – 400M+ residential IPs in more than [195 countries](/locations). - [ISP proxies](/proxy-types/isp-proxies) – 1,300,000+ ISP IPs. Create a free Bright Data account today to try out our scraping browser or test our proxies. Contact usStart free trial No credit card required [ ](https://www.linkedin.com/in/antonello-zanini/) Antonello Zanini Technical Writer 5.5 years experience Antonello Zanini is a technical writer, editor, and software engineer with 5M+ views. Expert in technical content strategy, web development, and project management. Expertise Web Development Web Scraping AI Integration [ View all articles ](https://brightdata.com/blog/authors/antonello-zanini) Table of Contents Dedicated Scraper APIs & No-Code Scrapers Over 1000 scrapers for all popular domains. Simplify your web scraping. [See pricing](/pricing/web-scraper "See pricing") Just want data? Skip scraping. Hundreds of ready-to-use datasets from all popular domains. [See pricing](/pricing/datasets "See pricing") [ ](https://news.ycombinator.com/submitlink?t=A+Complete+Guide+to+Puppeteer+Real+Browser+in+2026&u=https://brightdata.com/blog/web-data/puppeteer-real-browser) [ ](https://www.linkedin.com/shareArticle?mini=true&title=A+Complete+Guide+to+Puppeteer+Real+Browser+in+2026&url=https://brightdata.com/blog/web-data/puppeteer-real-browser) [ ](http://www.reddit.com/submit?title=A+Complete+Guide+to+Puppeteer+Real+Browser+in+2026&url=https://brightdata.com/blog/web-data/puppeteer-real-browser) ## You might also be interested in [ ](https://brightdata.com/blog/ai/openhuman-with-bright-data "Production-Ready Web Access in OpenHuman Through the Bright Data CLI") [AI Antonello Zanini Technical Writer ### Production-Ready Web Access in OpenHuman Through the Bright Data CLI Integrate Bright Data CLI with OpenHuman to enable production-ready web access and data collection for AI agents. 09-Sep-2026 12 min read ](https://brightdata.com/blog/ai/openhuman-with-bright-data) [ ](https://brightdata.com/blog/ai/minimax-m3-with-bright-data "Giving self-hosted MiniMax M3 agents live web access with Bright Data") [AI Satyam Tripathi Technical Writer ### Giving self-hosted MiniMax M3 agents live web access with Bright Data Self-hosted MiniMax M3 agents get live web access using Bright Data’s search and scraping tools. Bypass blocks and CAPTCHAs. 09-Sep-2026 54 min read ](https://brightdata.com/blog/ai/minimax-m3-with-bright-data) [ ](https://brightdata.com/blog/web-data/multimodal-web-scraping-with-minimax "Multimodal Web Scraping with MiniMax") [Web Data Antonello Zanini Technical Writer ### Multimodal Web Scraping with MiniMax Pair Bright Data Web Unlocker with MiniMax M3 vision to extract structured data from images and web page screenshots. 09-Sep-2026 4 min read ](https://brightdata.com/blog/web-data/multimodal-web-scraping-with-minimax)