SeleniumBase and Cloudflare Turnstile

The headless constraint, in the source

This is not folklore. browser_launcher.py contains a function whose only job is to enforce it:

def verify_pyautogui_has_a_headed_browser(driver):
    """PyAutoGUI requires a headed browser so that it can
    focus on the correct element when performing actions."""
    if getattr(driver, "_is_hidden", None):
        raise Exception(
            "PyAutoGUI can't be used in headless mode!"
        )

Every uc_gui_* method routes through the installer that calls it first, and _is_hidden is set from headless or headless2. So the rule is precise: true headless raises; a virtual display does not. Xvfb is a headed browser as far as this check is concerned.

The documentation says the same in prose, and adds a second reason worth knowing: "UC Mode is detectable in headless mode. Two: pyautogui doesn't work in headless mode." Running headless is both blocked here and a worse idea generally.

Three methods, three mechanisms

SeleniumBase's own example file annotates the difference, which is the clearest summary available:

sb.uc_gui_handle_captcha()  # PyAutoGUI Tabs + Spacebar
sb.uc_gui_click_captcha()   # PyAutoGUI mouse click
sb.solve_captcha()          # CDP Input.dispatchMouseEvent

Note the signature asymmetry, which trips people: uc_gui_click_captcha accepts retry and blind; uc_gui_handle_captcha accepts only frame. And solve_captcha() belongs to CDP Mode — its documented description is "Checks to see if a CAPTCHA is on the current page" and, if found, clicks it with an offset.

The project's own Turnstile examples have been rewritten to call solve_captcha(). If you are following a guide that only mentions uc_gui_click_captcha, it predates that.

What each one actually looks like

# The PyAutoGUI path. Needs a headed browser or a virtual display.
from seleniumbase import SB

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

# The CDP path. No PyAutoGUI, so no headed requirement from that check.
from seleniumbase import SB

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

uc_open_with_reconnect(url, reconnect_time=…) is the pattern the docs use throughout: it disconnects the driver during page load so the automation is not observable at the moment that matters, then reconnects. That reconnect window is why so many examples carry a sleep — it is not superstition, it is the driver being deliberately absent.

What discussion #2496 actually says

It is the top result for this subject and it is worth reading correctly, because its title is misleading about its own contents. The real title is *"Does cloudflare turnstile can't be bypass from seleniumbase for now . the cloudflare turnstile is sucess but error to find element the code is below"* — and the substance is in the middle of that sentence.

Turnstile passed. The asker's problem was finding a subsequent element afterwards. The maintainer's accepted answer points at the UC Mode examples and adds the operative detail: "Those checkboxes are located in iframes, so you need to switch into them first, carefully." A later reply notes the examples were updated to click through Shadow DOM.

So the thread is not evidence that SeleniumBase cannot pass Turnstile. It is evidence that the widget lives in an iframe inside a shadow root, and that ordinary selectors do not reach into it. That is a real and recurring problem, and it is a different one.

A third party in the same thread asserts that UC mode does not automatically solve Turnstile in web forms. That is a user's claim from February 2024, well before solve_captcha() existed, and it is worth treating as such rather than as documentation.

When to hand the token over instead

All three methods above are automation clicking a real challenge, and Cloudflare states that "Browser automation frameworks, such as Selenium, Puppeteer, Playwright, and Cypress, are not supported for solving production challenges. For automated Turnstile testing, use Turnstile test keys." SeleniumBase is a Selenium framework; it is inside that sentence.

So the decision is really about what you are testing. If the site is yours and the widget is only in the way, the dummy sitekeys remove the challenge from the test entirely and behave identically every run — Cloudflare's own recommendation, and it makes the whole uc_gui versus solve_captcha question moot.

If the challenge genuinely has to clear — staging behind a real widget, synthetic monitoring of your own production — fetching a token and writing it into the field is both simpler and less brittle than clicking, because it does not depend on the widget rendering where a mouse can reach it:

import json, os, urllib.request
from seleniumbase import SB

SITEKEY = "0x4AAAAAAA_target"
PAGE = "https://app.example.com/login"

req = urllib.request.Request(
    "https://api.solvegate.io/v1/solve",
    data=json.dumps({"gate": "turnstile", "sitekey": SITEKEY, "url": PAGE}).encode(),
    headers={
        "Authorization": f"Bearer {os.environ['SOLVEGATE_KEY']}",
        "Content-Type": "application/json",
    },
)
with urllib.request.urlopen(req, timeout=30) as res:
    token = json.load(res)["token"]

with SB(uc=True) as sb:
    sb.open(PAGE)
    sb.execute_script(
        'document.querySelector(\'[name="cf-turnstile-response"]\').value = arguments[0];',
        token,
    )
    sb.click("button[type=submit]")

A token typically returns in under 1.5 seconds. Prepaid credits run from $0.40 per 1,000 down to $0.075 at volume; failed solves are never billed; the first 1,000 are free.

Common questions

Related

Sources

• SeleniumBase — UC Mode documentation
• SeleniumBase discussion #2496 — Turnstile and iframes
• SeleniumBase on PyPI
• Cloudflare — unsupported environments

More in Guides