Web Scraping APIs

What Is SeleniumBase?

What Is SeleniumBase? — conceptual illustration
On this page

SeleniumBase is a Python automation and testing framework built on Selenium 4 whose UC Mode and CDP Mode make it one of the most effective Python tools for bypassing bot detection. UC Mode (Undetected-Chromedriver Mode) patches the chromedriver binary, launches Chrome browser-first, and disconnects the driver during sensitive moments so detection scripts see a clean session. It is unique among these tools for shipping built-in CAPTCHA handling.

Quick facts

TypeSelenium 4 framework + UC Mode / CDP Mode
LanguagePython (pytest/unittest integration)
Standout featureBuilt-in Turnstile / reCAPTCHA solving via PyAutoGUI
Key techniqueDisconnect/reconnect driver during page load + clicks
Main limitationUC Mode detectable in true headless; slower than vanilla Selenium

How UC Mode and CDP Mode work

UC Mode combines three techniques. First, it patches the chromedriver binary to randomise the window.cdc_* markers websites scan for. Second, it uses a browser-first launch: Chrome starts as a standalone clean process and chromedriver connects afterwards, instead of Chrome being launched through the driver with bot signatures from the start. Third — the clever part — it disconnects the driver (driver.service.stop()) during page load and clicks, scheduling the navigation/click via JavaScript while disconnected, then reconnects. Detection scripts that probe for chromedriver during those moments find nothing.

CDP Mode goes further, driving the page over the Chrome DevTools Protocol directly so there are no WebDriver artifacts at all — slower than vanilla Selenium but stealthier, and mixable with WebDriver when needed.

Built-in CAPTCHA solving

SeleniumBase is the only tool in this comparison with automatic CAPTCHA handling. uc_gui_click_captcha() and uc_gui_handle_captcha() use PyAutoGUI to move the OS-level mouse with natural curves and click the Turnstile / reCAPTCHA checkbox at a small random offset. Because PyAutoGUI operates outside the browser context entirely, detection scripts cannot distinguish it from real input. The catch: this needs a real display, so on Linux you must run under xvfb rather than true headless.

Strengths, costs, and when to use it

The repo ships 200+ working examples against real protected sites (Cloudflare, Imperva, DataDome, Kasada, PerimeterX, reCAPTCHA). Use it when: you need automatic CAPTCHA solving, want a full pytest/unittest testing framework, or face multi-layer protection in Python. Costs: a steep learning curve, a heavy dependency tree, 2–5× slower than vanilla Selenium because of reconnect overhead, and UC Mode is detectable in true headless (use xvfb). Pair it with residential proxies and incognito=True for best results.

Code example

python
from seleniumbase import SB

# UC Mode + automatic CAPTCHA solving + residential proxy
with SB(uc=True, proxy="user:pass@host:port", incognito=True) as sb:
    sb.uc_open_with_reconnect("https://cloudflare-protected-site.com", 4)
    sb.uc_gui_click_captcha()   # solves Turnstile / reCAPTCHA via PyAutoGUI
    sb.assert_text("Success")

Related terms

Concept map

How SeleniumBase connects

The terms most directly tied to this one. Hover a node to see its neighbours, click to preview, drag to rearrange.

0 terms · 0 connections
You are here · Web Scraping APIs
Building map…

Frequently asked questions

What is UC Mode in SeleniumBase?

UC Mode (Undetected-Chromedriver Mode) is SeleniumBase's stealth layer. It patches the chromedriver binary to randomise cdc_ markers, launches Chrome before connecting the driver, and disconnects the driver during page load and clicks so detection scripts cannot see chromedriver at the moments they check for it.

Can SeleniumBase solve CAPTCHAs automatically?

Yes — it is the only tool in this comparison with built-in CAPTCHA handling. uc_gui_click_captcha() uses PyAutoGUI to click Turnstile/reCAPTCHA challenges at the OS level, which is invisible to in-browser detection. It requires a display (xvfb on Linux), so it does not work in true headless.

Why is UC Mode slower than normal Selenium?

The disconnect/reconnect mechanism adds 0.1–1 second of latency per sensitive operation, making UC Mode roughly 2–5× slower and CDP Mode 1.5–3× slower than vanilla Selenium. That is the cost of appearing as a clean browser session during detection windows.

Does UC Mode work in headless mode?

Not reliably — UC Mode is detectable in true headless. On Linux the recommended approach is a virtual display via xvfb=True, which gives a real rendering context while still running on a server.

Last updated: 2026-05-28