How to use SeleniumBase UC mode to Bypass bot detection

Getting blocked by anti-bot systems when scraping websites is frustrating. Standard Selenium setups leak information that makes your automated browser obvious to detection services.

SeleniumBase UC Mode solves this problem. It's an enhanced version of undetected-chromedriver built directly into the SeleniumBase framework with additional features, bug fixes, and specialized methods for bypassing CAPTCHAs.

In this guide, you'll learn how to set up and use SeleniumBase UC Mode effectively. We'll cover installation, basic usage, CAPTCHA handling, proxy integration, and advanced techniques for avoiding detection.

What is SeleniumBase UC Mode?

SeleniumBase UC Mode (Undetected-Chromedriver Mode) makes automated browsers appear human by modifying how chromedriver interacts with Chrome. This lets your scripts evade detection from anti-bot services like Cloudflare, DataDome, and Imperva.

UC Mode accomplishes this through three primary techniques:

First, it renames Chrome DevTools Console variables that anti-bot systems scan for. Standard Selenium exposes telltale variable names that scream "automated browser."

Second, UC Mode launches Chrome browsers before attaching chromedriver to them. Normal Selenium does this in reverse, which creates detectable browser configurations.

Third, it disconnects chromedriver from Chrome during sensitive actions like page loads and button clicks. Websites typically check for automation during these specific events.

The result is a browser that passes most fingerprint checks and CAPTCHA challenges that would normally block standard Selenium scripts.

How UC Mode Avoids Detection (Technical Deep Dive)

Understanding UC Mode's internals helps you troubleshoot when things go wrong.

DevTools Variable Renaming

Standard chromedriver creates JavaScript variables in the browser's DevTools Console. These variables have predictable names that anti-bot scripts scan for.

When a page loads JavaScript that checks for window.cdc_adoQpoasnfa76pfcZLmcfl_ or similar variables, standard Selenium fails immediately. UC Mode patches chromedriver to rename these variables before they're created.

Browser Launch Sequence

Normal Selenium launches chromedriver first, then chromedriver spawns Chrome. This creates detectable configurations in Chrome's startup parameters.

UC Mode reverses this. It launches Chrome as a standalone browser first, then attaches chromedriver afterward. The browser initialization happens without any chromedriver interference, producing a fingerprint identical to a human-launched browser.

Strategic Disconnection

The most powerful technique is disconnecting chromedriver during detection-sensitive moments.

When chromedriver is connected to Chrome, it maintains a debugging connection. Anti-bot systems check for this connection during page loads, form submissions, and clicks.

UC Mode uses raw Selenium's built-in service methods:

driver.service.stop()    # Disconnect chromedriver
driver.service.start()   # Reconnect chromedriver

The uc_*() methods wrap these calls with proper timing to keep chromedriver disconnected exactly when websites check for automation.

UC Mode vs Regular Undetected-Chromedriver

SeleniumBase UC Mode builds on the popular undetected-chromedriver package but adds several improvements.

The regular undetected-chromedriver library requires manual driver management and has limited CAPTCHA-solving capabilities. SeleniumBase handles driver downloads and version matching automatically.

UC Mode also includes specialized uc_*() methods designed specifically for bypassing CAPTCHAs. These methods time the disconnection and reconnection of chromedriver precisely to avoid triggering detection.

Another advantage is the SB manager format, which provides context management and cleanup. This prevents common issues like orphaned browser processes and memory leaks during long scraping sessions.

Here's a comparison of the two approaches:

Installing SeleniumBase with UC Mode

Installation takes one command:

pip install seleniumbase

SeleniumBase includes UC Mode by default. No additional packages or driver downloads are required.

The framework automatically downloads the correct chromedriver version to match your Chrome installation. This eliminates the version mismatch errors that plague manual Selenium setups.

Verify your installation works:

from seleniumbase import Driver

driver = Driver(uc=True)
driver.get("https://nowsecure.nl")
driver.quit()

If the page loads without triggering the Cloudflare challenge, UC Mode is working correctly.

Basic Usage: Two Syntax Options

SeleniumBase UC Mode supports two main syntax formats. Each has different use cases.

The Driver Format

The Driver format is simpler and works well for quick scripts:

from seleniumbase import Driver

driver = Driver(uc=True)
driver.get("https://example.com")
# perform your scraping
driver.quit()

This format gives you a driver object that works similarly to standard Selenium WebDriver.

However, the Driver format lacks some functionality needed for CAPTCHA solving on headless Linux machines. It doesn't include the virtual display that PyAutoGUI requires for GUI-based CAPTCHA clicks.

The SB Manager Format

The SB manager provides more features and better resource management:

from seleniumbase import SB

with SB(uc=True) as sb:
    sb.uc_open_with_reconnect("https://gitlab.com/users/sign_in", 4)
    sb.uc_gui_click_captcha()
    # continue with your automation

The context manager automatically handles browser cleanup. Even if your script crashes, the browser closes properly.

For production scraping and CAPTCHA bypass scenarios, use the SB format. It includes the virtual display support needed for headless servers.

Core UC Mode Methods

SeleniumBase UC Mode provides several specialized methods for stealthy browsing.

Opening URLs Safely

Standard driver.get() can trigger detection on protected sites. UC Mode offers alternatives:

# Standard reconnect method
sb.uc_open_with_reconnect(url, reconnect_time=4)

This method opens the URL in a new tab while chromedriver is disconnected. The reconnect_time parameter specifies how many seconds to wait before reconnecting the driver.

# Open with indefinite disconnect
sb.uc_open_with_disconnect(url, timeout=10)

This keeps chromedriver disconnected until you manually call sb.connect(). Use this when you need to perform manual actions before reconnecting.

# Breakpoint for debugging
sb.uc_open_with_reconnect(url, reconnect_time="breakpoint")

Setting reconnect_time to "breakpoint" pauses execution indefinitely. This lets you manually interact with the page to test if detection is working. Type 'c' and press Enter to continue.

Clicking Without Detection

Regular Selenium clicks can trigger bot detection. UC Mode schedules clicks to happen while chromedriver is disconnected:

sb.uc_click(selector, reconnect_time=3)

This method uses JavaScript's setTimeout() to schedule the click, disconnects chromedriver, waits for the click to execute, then reconnects.

The technique works because websites typically only check for automation during interactive events. By disconnecting before the click happens, your bot remains invisible.

Manual Reconnection

For fine-grained control, use the disconnect and connect methods directly:

sb.disconnect()
# chromedriver is now disconnected
# perform manual actions or wait
sb.connect()
# chromedriver is reconnected

You can also use the shorthand reconnect method:

sb.reconnect(timeout=5)

This disconnects, waits the specified seconds, then reconnects automatically.

Bypassing CAPTCHAs with UC Mode

SeleniumBase UC Mode includes built-in methods for handling common CAPTCHA types.

Cloudflare Turnstile

Cloudflare's Turnstile is the most common CAPTCHA you'll encounter. UC Mode handles it automatically in many cases:

from seleniumbase import SB

with SB(uc=True, test=True) as sb:
    sb.uc_open_with_reconnect("https://seleniumbase.io/apps/turnstile", 2)
    sb.uc_gui_handle_captcha()
    sb.assert_element("img#captcha-success", timeout=3)

The uc_gui_handle_captcha() method auto-detects the CAPTCHA type and clicks the checkbox using PyAutoGUI. This simulates a real mouse click outside of chromedriver's control.

For more stubborn Turnstiles, use the explicit click method:

sb.uc_gui_click_captcha()

This performs a more forceful click that works on stricter implementations.

Google reCAPTCHA

reCAPTCHA is harder to bypass because Google uses advanced AI to detect unusual patterns.

sb.uc_gui_click_rc(frame="iframe", retry=True, blind=False)

The retry parameter attempts the click again after a page reload if the first attempt fails.

Important: reCAPTCHA bypass may only work a few times before Google's AI flags your activity. This happens regardless of whether Selenium was detected—reCAPTCHA looks for behavioral patterns beyond just automation signatures.

CAPTCHA After Form Submission

Some sites only show CAPTCHAs after you submit a form:

from seleniumbase import SB

with SB(uc=True, test=True, incognito=True) as sb:
    url = "https://ahrefs.com/website-authority-checker"
    sb.uc_open_with_reconnect(url)
    sb.type('input[placeholder="Enter domain"]', "github.com")
    sb.uc_click('span:contains("Check Authority")', reconnect_time=3.25)
    sb.uc_gui_click_captcha()

The key is using uc_click() for the submit button with an appropriate reconnect time. This keeps chromedriver disconnected during the CAPTCHA challenge.

Using Proxies with SeleniumBase UC Mode

For large-scale scraping, you'll need to rotate IP addresses to avoid rate limits and blocks.

Basic Proxy Setup

SeleniumBase accepts proxy configuration through the Driver or SB manager:

from seleniumbase import SB

proxy = "123.45.67.89:8080"

with SB(uc=True, proxy=proxy) as sb:
    sb.uc_open_with_reconnect("https://httpbin.org/ip", 4)
    print(sb.get_text("pre"))

This routes all requests through the specified proxy server.

Authenticated Proxies

Most commercial proxy services require authentication:

from seleniumbase import SB

proxy = "username:password@proxy.example.com:8080"

with SB(uc=True, proxy=proxy) as sb:
    sb.uc_open_with_reconnect("https://httpbin.org/ip", 4)

SeleniumBase handles proxy authentication automatically. No Chrome extensions or additional configuration required.

Residential Proxies for Better Success Rates

Datacenter IP addresses often get flagged immediately by anti-bot systems. Residential proxies use real ISP addresses that appear as normal home users.

When scraping sites with aggressive bot protection, residential proxies from providers like Roundproxies significantly improve success rates. The IP addresses look legitimate because they come from actual ISP networks.

Combine residential proxies with UC Mode for the best results:

from seleniumbase import SB

residential_proxy = "user:pass@gate.roundproxies.com:8080"

with SB(uc=True, proxy=residential_proxy, incognito=True) as sb:
    sb.uc_open_with_reconnect("https://protected-site.com", 4)
    sb.uc_gui_click_captcha()

The combination of UC Mode's browser fingerprint masking and residential proxy IP addresses passes most anti-bot systems.

Running UC Mode on Linux Servers

Headless Linux servers present unique challenges for UC Mode.

The Headless Problem

UC Mode is detectable when running in true headless mode. The browser fingerprint differs enough from normal Chrome that anti-bot systems can identify it.

Don't use headless=True with UC Mode. Instead, use the virtual display:

from seleniumbase import SB

with SB(uc=True, xvfb=True) as sb:
    sb.uc_open_with_reconnect("https://nowsecure.nl", 4)

The xvfb=True parameter creates a virtual display using Xvfb (X Virtual Framebuffer). Your browser runs in "headed" mode within this virtual display, but no actual monitor is needed.

Installing Xvfb

On Ubuntu/Debian:

sudo apt-get install xvfb

On CentOS/RHEL:

sudo yum install xorg-x11-server-Xvfb

SeleniumBase uses Xvfb automatically when the SB manager detects a headless environment.

Multithreaded UC Mode

Running multiple UC Mode instances simultaneously requires careful setup.

With pytest

The simplest approach uses pytest with the xdist plugin:

pytest my_script.py --uc -n 4

This runs your tests across 4 browser instances automatically. pytest-xdist handles the thread management.

Without pytest

For custom multithreading, add the -n flag to sys.argv and use ThreadPoolExecutor:

import sys
from concurrent.futures import ThreadPoolExecutor
from seleniumbase import Driver

sys.argv.append("-n")

def scrape_url(url):
    driver = Driver(uc=True)
    try:
        driver.get(url)
        # your scraping logic
        return driver.page_source
    finally:
        driver.quit()

urls = ["https://example.com/page1", "https://example.com/page2"]

with ThreadPoolExecutor(max_workers=4) as executor:
    results = list(executor.map(scrape_url, urls))

The -n flag tells SeleniumBase to enable thread-locking for shared resources.

Common Issues and Solutions

Detection Still Happening

If sites still detect your bot, try these fixes:

Add incognito mode - Some sites detect non-incognito profiles:

with SB(uc=True, incognito=True) as sb:

Increase reconnect time - Give more time before reconnecting chromedriver:

sb.uc_open_with_reconnect(url, reconnect_time=6)

Add delays between actions - Acting too fast triggers behavioral detection:

sb.sleep(random.uniform(1, 3))

Use test mode - Enables additional stealth features:

with SB(uc=True, test=True) as sb:

Browser Crashes

Memory issues often cause crashes during long sessions. Use the SB manager format which properly cleans up resources.

For very long sessions, periodically restart the browser:

sb.get_new_driver(undetectable=True)

If crashes persist, limit the number of tabs and close them after use:

sb.switch_to_default_window()  # Return to main window
sb.close_extra_windows()        # Close all except main

CAPTCHA Click Fails

If uc_gui_click_captcha() doesn't work:

Check frame selector - The CAPTCHA might be in a different iframe:

sb.uc_gui_click_captcha(frame='iframe[title*="challenge"]')

Use blind retry - Click at last known coordinates without confirming:

sb.uc_gui_click_captcha(retry=True, blind=True)

Check your IP reputation - Even perfect automation fails if your IP is blacklisted. Test with a residential proxy to isolate the issue.

User Data Directory Issues

Never share user data directories between UC Mode and regular Chrome. This contaminates the profile and increases detection.

To use a custom profile:

from seleniumbase import SB

with SB(uc=True, user_data_dir="/path/to/profile") as sb:
    sb.uc_open_with_reconnect("https://example.com", 4)

Create a fresh directory specifically for UC Mode automation.

Best Practices for Production Scraping

Follow these guidelines for reliable, long-running scrapers.

Rate Limiting

Anti-bot systems track request frequency. Space your requests appropriately:

import random
import time

def scrape_with_delays(sb, urls):
    for url in urls:
        sb.uc_open_with_reconnect(url, 4)
        # random delay between 2-5 seconds
        time.sleep(random.uniform(2, 5))

Session Rotation

Don't use the same browser session indefinitely. Rotate sessions every 50-100 requests:

request_count = 0
max_requests = 75

for url in urls:
    if request_count >= max_requests:
        sb.get_new_driver(undetectable=True)
        request_count = 0
    
    sb.uc_open_with_reconnect(url, 4)
    request_count += 1

Error Handling

Implement robust error handling for production reliability:

from seleniumbase import SB

def safe_scrape(url, max_retries=3):
    for attempt in range(max_retries):
        try:
            with SB(uc=True, incognito=True) as sb:
                sb.uc_open_with_reconnect(url, 4)
                if sb.is_element_visible('iframe[src*="challenge"]'):
                    sb.uc_gui_click_captcha()
                return sb.get_page_source()
        except Exception as e:
            if attempt == max_retries - 1:
                raise
            time.sleep(5 * (attempt + 1))  # Exponential backoff

UC Mode vs CDP Mode

SeleniumBase also offers CDP Mode, which is the successor to UC Mode for advanced use cases.

CDP Mode uses Chrome DevTools Protocol directly instead of WebDriver. This provides even stealthier automation because there's no chromedriver to detect.

from seleniumbase import SB

with SB(uc=True, test=True) as sb:
    sb.activate_cdp_mode("https://gitlab.com/users/sign_in")
    sb.sleep(2)
    sb.solve_captcha()

CDP Mode works by disconnecting WebDriver entirely after navigating to the URL. All subsequent actions use CDP commands that don't trigger typical automation detection.

Use CDP Mode when standard UC Mode fails. It requires more setup but handles the most aggressive anti-bot systems.

Final Thoughts

SeleniumBase UC Mode transforms standard Selenium into a stealth automation tool. The key techniques—driver disconnection during sensitive actions, modified browser variables, and specialized CAPTCHA methods—let you bypass most anti-bot protections.

For best results, combine UC Mode with residential proxies, appropriate delays between actions, and the SB manager format for proper resource handling.

Start with basic UC Mode for most sites. Upgrade to CDP Mode for heavily protected targets. And remember that no solution is 100% undetectable—the goal is staying under the radar long enough to complete your tasks.

FAQ

Does SeleniumBase UC Mode work in headless mode?

No, UC Mode is detectable in true headless mode. Use xvfb=True on Linux servers to run a headed browser in a virtual display instead.

Can UC Mode bypass all CAPTCHAs?

UC Mode handles Cloudflare Turnstile reliably. Google reCAPTCHA is harder because it uses AI behavioral analysis. Success depends on your overall automation patterns, not just browser fingerprint.

Is UC Mode the same as undetected-chromedriver?

UC Mode is based on undetected-chromedriver but includes additional features: automatic driver management, specialized CAPTCHA methods, the SB manager format, and better integration with the SeleniumBase testing framework.

What's the difference between UC Mode and CDP Mode?

UC Mode uses modified chromedriver with strategic disconnection. CDP Mode bypasses WebDriver entirely by using Chrome DevTools Protocol directly. CDP Mode is stealthier but requires different method calls.