Web Scraping APIs

What Is SeleniumBase?

What Is SeleniumBase? — conceptual illustration
On this page

SeleniumBase is a Python framework for automating and testing browsers, built on top of Selenium 4. Its two notable features, UC Mode and CDP Mode, are designed to make automated Chrome behave more like an ordinary browser session. UC Mode (Undetected-Chromedriver Mode) adjusts the chromedriver program, starts Chrome on its own first, and briefly drops the automation connection during page loads and clicks — so the running browser presents a consistent configuration. It is one of the few tools of its kind that also includes built-in CAPTCHA handling. As with any automation framework, use it only on sites and data you own, control, or are permitted to access.

Quick facts

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

How UC Mode and CDP Mode work

UC Mode combines three tricks. First, it patches the chromedriver binary (chromedriver is the program Selenium uses to control Chrome) to randomise the window.cdc_* values — telltale variables that automation tools leave behind and that websites scan for. Second, it uses a browser-first launch: Chrome starts as a normal, clean process and chromedriver connects to it afterwards, instead of Chrome being opened by the driver and carrying automation signatures from the very first moment. Third — the clever part — it disconnects the driver (driver.service.stop()) during page loads and clicks. It schedules the navigation or click through JavaScript while disconnected, then reconnects. This keeps the browser's runtime state consistent during the moments a page is most actively inspecting its environment.

CDP Mode goes a step further: it controls the page directly through the Chrome DevTools Protocol (the same channel Chrome's own dev tools use), so the usual WebDriver fingerprints are not present. It is slower than plain Selenium but presents a cleaner environment, and you can mix it with WebDriver when you need to.

Built-in CAPTCHA handling

SeleniumBase is the only tool in this comparison that handles CAPTCHAs automatically. uc_gui_click_captcha() and uc_gui_handle_captcha() use PyAutoGUI — a library that controls the real mouse and keyboard at the operating-system level — to move the cursor along natural curves and click the Turnstile or reCAPTCHA checkbox at a small random offset. Because PyAutoGUI works at the operating-system level rather than inside the browser, the interaction looks like ordinary mouse input. This is intended for verification on services you are authorized to access. The catch: it needs an actual display, so on Linux you must run it under xvfb (a virtual screen) rather than true headless (no screen at all).

Strengths, costs, and when to use it

The repo ships 200+ working examples that run against real protected sites (Cloudflare, Imperva, DataDome, Kasada, PerimeterX, reCAPTCHA). Use it when: you want built-in CAPTCHA handling, a full pytest/unittest testing framework, or are working with protected sites you are authorized to access in Python. Costs: a steep learning curve, a heavy set of dependencies, and speeds 2–5× slower than plain Selenium because of the disconnect/reconnect overhead. UC Mode is also detectable in true headless, so use xvfb instead. It is commonly paired with residential proxies (IP addresses tied to home internet connections) and incognito=True.

Code example

python
from seleniumbase import SB

# UC Mode + built-in CAPTCHA handling + residential proxy
# Use only on sites and data you are permitted to access.
with SB(uc=True, proxy="user:pass@host:port", incognito=True) as sb:
    sb.uc_open_with_reconnect("https://your-authorized-site.com", 4)
    sb.uc_gui_click_captcha()   # handles 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 consistency layer. It adjusts the chromedriver program to randomise the cdc_ markers that automation tools normally leave behind, starts Chrome before connecting the driver, and disconnects the driver during page loads and clicks, keeping the browser's runtime state consistent during sensitive operations.

Can SeleniumBase solve CAPTCHAs automatically?

Yes — it is one of the few tools in this comparison that includes CAPTCHA handling out of the box. uc_gui_click_captcha() uses PyAutoGUI to click Turnstile and reCAPTCHA challenges at the operating-system level, like ordinary mouse input, on services you are authorized to access. It needs a display (xvfb on Linux), so it does not work in true headless mode.

Why is UC Mode slower than normal Selenium?

The disconnect/reconnect step adds 0.1–1 second of delay each time it touches a sensitive operation. That makes UC Mode roughly 2–5× slower and CDP Mode 1.5–3× slower than plain Selenium. It is the cost of keeping a consistent browser session during sensitive operations.

Does UC Mode work in headless mode?

Not reliably — UC Mode can be detected in true headless (running with no screen). On Linux the recommended fix is a virtual display with xvfb=True, which gives Chrome a real place to render while still running on a server.

Last updated: 2026-05-31