How to use SeleniumBase UC mode

What is SeleniumBase UC mode?

SeleniumBase is a Python test framework built on top of Selenium. It wraps WebDriver in a much shorter API, and it bundles a set of things Selenium makes you assemble yourself: driver management, waits, and a stealth driver.

UC mode is that stealth driver, and the name is inherited from undetected-chromedriver, whose approach it follows. Instead of driving a bundled Chromium the way Playwright does, it patches ChromeDriver and drives the Chrome you already have installed, which removes a whole class of differences between your browser and a real one rather than papering over them afterwards.

That is why people pick it: it is one argument, and the properties it fixes are genuinely present rather than spoofed. This covers what turning it on changes, and the two costs of leaving it on.

Turning it on

pip install seleniumbase

from seleniumbase import Driver

driver = Driver(uc=True, headless=True)
driver.get("https://example.com")

That is the whole thing, and it is the cleanest result we measured: every browser signal we checked came back right, consistently, with no version pin needed.

It has two costs, and neither is documented anywhere we could find. It takes seven times longer to start, and it stops sending your proxy password.

What it looks like running

This is your actual Chrome. The window belongs to an application called Google Chrome, where a Playwright or Patchright window belongs to Google Chrome for Testing. That is the difference the section below is measuring: the properties UC mode does not have to fix are the ones a real Chrome install already has.

One thing the screenshot does not show, and we looked: no automation banner. Neither with uc=True nor without it did Chrome display the "controlled by automated test software" infobar, so that is not a way to tell the two apart.

What it reports

Two of those rows change and four do not, which is the useful part.

UC mode is doing less than its reputation suggests, because SeleniumBase was already doing most of it. window.chrome, the plugin list and the platform are correct with UC mode off, for the same reason Patchright's improve when you pass channel="chrome": SeleniumBase drives the Chrome you have installed rather than a bundled Chromium, so those properties are real rather than restored.

What UC mode adds on top is the webdriver flag and the user agent.

Reading the signals yourself

The table above is four properties any page can read. This is the whole check, and it runs the same against any driver you point it at:

from seleniumbase import Driver

SIGNALS = """() => ({
    ua:        navigator.userAgent,
    platform:  navigator.platform,
    webdriver: String(navigator.webdriver),
    chrome:    typeof window.chrome,
    plugins:   navigator.plugins.length,
})"""

for uc in (False, True):
    driver = Driver(uc=uc, headless=True)
    try:
        driver.get("https://example.com")
        print(uc, driver.execute_script(f"return ({SIGNALS})()"))
    finally:
        driver.quit()

Time the launch while you are there, because that is the cost the next section is about:

import time

start = time.perf_counter()
driver = Driver(uc=True, headless=True)
print(f"launch took {time.perf_counter() - start:.1f}s")
driver.quit()

Consistency across the four signals

Across everything we ran on the same day, this was the only configuration where all four signals were right at once and the platform agreed with the user agent:

• Plain Playwright announced HeadlessChrome and left navigator.webdriver true.
• Patchright cleared the flag and kept HeadlessChrome in both configurations.
• playwright-stealth fixed three signals and then reported macOS and Win32 in the same call.
• undetected-chromedriver would not connect at all until given a version pin.

The full table is in how to choose an anti-detect browser.

The launch-time cost

1.4 seconds to 10.4. That is nine seconds every time you open a browser.

It matters enormously or not at all depending on your shape. One long-lived browser working through a queue pays it once. A worker that starts a fresh browser per job, which is the usual pattern when each job needs its own proxy session, pays it every time: at ten thousand jobs that is twenty-five hours of launching.

That is the trade nobody states, and it is worth measuring on your own machine before you assume either answer.

Version pinning

Worth saying plainly, because the alternative did not. In the same session, undetected-chromedriver 3.5.5 failed with session not created: cannot connect to chrome and only launched once given version_main=151. SeleniumBase needed no equivalent argument.

from seleniumbase import Driver

driver = Driver(uc=True, headless=True)
driver.get("https://example.com")

Adding a proxy

SeleniumBase takes a proxy as a single string, where the Playwright-family tools take a dict:

driver = Driver(uc=True, headless=True,
                proxy="user-session-abc123:secret@gate.example.com:7000")

That difference is worth pausing on, because it is where credentials break. A password containing a colon or an at sign terminates the string early and the endpoint answers 407 with nothing naming the cause. The format converter will encode a credential correctly for this form and for the separate-field form the other tools want.

Two provider-side traps sit under all of them. The session token is in the username at some providers and the password at others. And some providers take no username and password at all, expecting your IP on an allowlist. We record what each provider states about both on its provider page, dated, and say so where a provider states nothing.

UC mode and proxy credentials

Measured separately and worth knowing before you turn UC mode on. With uc=True, SeleniumBase never sent the credentials to an authenticated proxy: sixteen requests arrived and not one carried a Proxy-Authorization header, in three consecutive runs, headed and headless alike. With UC mode off it authenticated and loaded the page.

The details, and what eight other configurations did against the same proxy, are in how to use an authenticated proxy in Selenium.

Limitations

No anti-bot system, no evasion claim, no recommendation between these tools. Six signals and one timing from SeleniumBase 4.52.4 on Chrome 151, on one machine, on one day. Launch time especially is machine-dependent and worth re-running on your own hardware rather than taking ours.