How to Use SeleniumBase with Proxies: 2026 Complete Guide
TL;DR
SeleniumBase reads a proxy from one of three interchangeable entry points — the --proxy pytest CLI flag, the proxy argument to Driver(), or the proxy argument to the SB() context manager — and all three route through the same driver-launch code internally.
Authenticated HTTP/HTTPS proxies on Chrome and Edge work without a login popup because SeleniumBase writes a Manifest V3 browser extension on the fly that answers each 407 challenge automatically; you never need a separate anonymizing proxy layer for those two browsers.
Firefox handles proxies differently and does not auto-fill credentials. SeleniumBase sets Firefox's native network.proxy.* preferences (including SOCKS4/5/5h), but there is no credential-injection step, so an authenticated proxy still triggers Firefox's own login prompt.
SOCKS4, SOCKS5, and SOCKS5h are valid proxy schemes in both the CLI flag and the Python constructor (for example socks5://host:port), confirmed directly from SeleniumBase 4.51.10's proxy_helper.validate_proxy_string() source.
UC Mode accepts the same proxy= argument as a standard session, but SeleniumBase does not ship a built-in per-request rotation scheduler — rotating IPs across requests has to come from the proxy gateway itself or from re-launching the driver with a new value.
A Chrome 137 change to extension internals briefly broke SeleniumBase's proxy-auth extension. Current releases include the fix; on newer Chrome builds where a login popup still appears, switching into CDP Mode before navigating is the documented workaround.
Nstdata's residential gateway plugs into any of the three integration points with one string (username:password@gw-us.nstdata.io:24125), skipping the local anonymizing-proxy layer that vanilla Selenium, Puppeteer, and Playwright setups typically need for authenticated proxies.
Introduction: What SeleniumBase's Proxy Support Actually Covers
SeleniumBase is a Python browser automation and testing framework built on top of Selenium WebDriver and pytest, and it adds a proxy layer that goes beyond what raw Selenium exposes out of the box. Where plain Selenium's --proxy-server Chrome option can't carry a username and password, SeleniumBase parses a username:password@host:port string, builds a small on-the-fly browser extension for Chromium browsers, and wires that extension to answer authentication challenges automatically. The framework, published as seleniumbase on PyPI, is currently at version 4.51.10 and is maintained by Michael Mintz on GitHub. The framework's own proxy documentation covers the CLI flag syntax used throughout this guide in its detailed setup reference.
This guide covers the three ways to hand SeleniumBase a proxy, what actually happens under the hood for authenticated proxies, where SOCKS5 and UC Mode fit in, where the honest limits are (Firefox credential handling, the lack of a rotation scheduler, a real Chrome-version regression), and how to point the setup at Nstdata's residential gateway.
Install SeleniumBase and Confirm the Setup
Installing SeleniumBase pulls in Selenium, pytest, and the framework's own driver-management tooling in one step:
seleniumbase install chromedriver downloads a chromedriver build that matches the Chrome version already on the machine, which is what makes later proxy testing predictable — a mismatched driver/browser pair produces its own connection errors that have nothing to do with proxy configuration and are easy to misdiagnose as a proxy problem. Confirm the install with:
SeleniumBase answers this in one line: pass the proxy as a string, and the format is identical whether it comes from the command line or from Python. The CLI accepts it as a pytest flag:
The Python API exposes the same value as a keyword argument on both Driver() and the SB() context manager — confirmed by inspecting both signatures directly in the installed package:
from seleniumbase import Driver
import inspect
print(inspect.signature(Driver).parameters["proxy"].default)# None
from seleniumbase import Driver
driver = Driver(browser="chrome", headless=True, proxy="USERNAME:PASSWORD@SERVER:PORT")driver.get("https://example.com")driver.quit()
Unauthenticated proxies drop the USERNAME:PASSWORD@ portion entirely; SeleniumBase's validate_proxy_string() function treats a bare ip_address:port or server:port as equally valid.
Basic Implementation: An Authenticated Proxy End to End
Passing proxy="user:pass@host:port" to Driver() is answered by one specific mechanism in Chrome and Edge: SeleniumBase's create_proxy_ext() function writes a Manifest V3 extension with a chrome.proxy.settings.set() call and a chrome.webRequest.onAuthRequired listener that returns the stored credentials whenever the proxy issues a 407 challenge. To verify this is real and not just documented behavior, this guide ran it against a local authenticated proxy (mitmproxy, configured with a test username and password) and captured the traffic:
from seleniumbase import Driver
driver = Driver( browser="chrome", headless=True, proxy="testuser:testpass123@127.0.0.1:8899",)driver.get("http://internal-test-host:9000/")print(driver.page_source[:80])driver.quit()
The proxy's own log showed exactly the sequence SeleniumBase's source implies: the browser's first request came in with no auth header and got a 407 Proxy Authentication Required response, then the extension's onAuthRequired callback fired, and the identical request was retried with the stored credentials and returned 200 OK with the expected page body — with no popup, no manual retry, and no extra library. That handshake, not just the presence of a proxy parameter, is what "authenticated proxy support" means in SeleniumBase.
Take a Quick Look
If your SeleniumBase runs keep hitting proxy auth popups or getting blocked mid-session, Nstdata's residential gateway gives you a stable, pre-authenticated `username:password@host:port` string with session control built in, so the same `proxy=` argument above just keeps working.
If the printed IP matches the proxy's own address rather than the machine's real IP, the proxy is in the request path. A mismatch here usually means the proxy value was malformed (a stray http:// prefix in front of an already-scheme-prefixed SOCKS string is a common cause) rather than an auth failure, since auth failures in Chrome typically surface as a blank tab or an aborted navigation instead of a wrong IP.
Choosing a Proxy Provider for Browser Automation
A proxy string is only as reliable as the IPs behind it, and browser automation is harder on a proxy pool than simple HTTP requests are: a multi-page SeleniumBase flow needs the same exit IP to persist across several navigations, and a pool of flagged or overused datacenter IPs shows up as failed logins and CAPTCHA walls rather than clean errors. Nstdata is a proxy infrastructure provider whose residential lines are built around exactly that persistence requirement, sold either as pay-as-you-go traffic or as monthly packages, and they fit teams running scraping, price-monitoring, or account-management automation through tools like SeleniumBase rather than through raw HTTP clients. The gateway takes the same username:password@host:port shape used throughout this guide, so switching a test suite from a temporary proxy to a production one is a one-line change.
Sticky or rotating sessions on demand — Residential Prime Proxies support both a fixed session (the same exit IP for as long as a login flow or multi-page crawl needs it) and per-request rotation, matching how SeleniumBase's proxy= argument treats a session as one fixed endpoint for the life of the driver.
HTTP(S) and SOCKS5 on the same gateway — both protocols map directly onto the scheme values SeleniumBase's validate_proxy_string() already accepts (http, https, socks4, socks5, socks5h), so testing both transports is a one-line change, not a different integration.
195 tracked locations with country, city, and ASN targeting — useful when a SeleniumBase suite needs to check how a page renders or gates content for a specific region.
Residential Prime Proxies list a 99.98% success rate against 110M+ residential IPs at $1.60/GB on the 50GB package, and Residential Lite Proxies list a 99.5% success rate; both figures come from Nstdata's own pricing pages and are worth re-checking there before basing a purchase decision on them, since proxy providers update pool size and pricing frequently.
The gateway itself is a single host and port shared across protocols, documented in Nstdata's integration guide:
Nstdata's own integration examples for vanilla Selenium, Puppeteer, and Playwright route this same gateway through the proxy-chain library to work around those tools' lack of inline proxy credentials — a step SeleniumBase's built-in extension handling makes unnecessary.
Advanced Patterns: SOCKS5, UC Mode, and Rotation
SOCKS5 works through the identical proxy= argument, just with the scheme spelled out:
from seleniumbase import Driver
driver = Driver(browser="chrome", headless=True, proxy="socks5://USERNAME:PASSWORD@SERVER:PORT")driver.get("https://api.ipify.org")driver.quit()
SeleniumBase's scheme parser also accepts socks4:// and socks5h:// (the latter resolves DNS through the proxy rather than locally), and passes whichever scheme is detected into the same Chrome extension that handles HTTP authentication, so an authenticated SOCKS5 proxy goes through the same onAuthRequired flow verified above rather than a separate code path.
UC Mode — SeleniumBase's undetected-chromedriver integration for sites with stricter bot detection — takes the same argument:
from seleniumbase import Driver
driver = Driver(uc=True, headless=False, proxy="USERNAME:PASSWORD@SERVER:PORT")driver.uc_open_with_reconnect("https://example.com", reconnect_time=4)driver.quit()
What UC Mode does not add is a rotation scheduler. SeleniumBase ships a static PROXY_LIST "phone book" in seleniumbase/config/proxy_list.py so a named key can stand in for a full proxy string on the CLI, and a --multi-proxy flag that exists specifically to let parallel pytest workers (pytest -n) each build their own proxy extension without file-lock contention — neither one rotates the exit IP between requests inside a single run. Rotation across requests has to come from re-launching the driver with a different proxy value or from the gateway itself rotating IPs server-side, which is what a rotating-session proxy plan is for.
Honest Limits
Three limits are worth planning around rather than discovering mid-project. First, Firefox is not a drop-in substitute for Chrome here: SeleniumBase sets Firefox's proxy through native network.proxy.type, network.proxy.http, and network.proxy.socks* preferences, including full SOCKS4/5/5h support, but there is no equivalent to the Chrome extension's credential auto-fill, so an authenticated proxy on Firefox still produces a native browser login prompt that a headless run can't dismiss. Second, the extension-based mechanism is tied to Chrome's own extension platform, which means it can break when Chrome changes that platform: a Chrome 137 update changed extension internals in a way that broke SeleniumBase's on-the-fly proxy-auth extension for a period in 2025, documented in a maintainer discussion thread, and the fix landed in a SeleniumBase release rather than being something a user could work around in their own test code. Third, there's no built-in rotation scheduler, as covered above — SeleniumBase gives you a clean single-proxy-per-session primitive, and building a rotation strategy on top of it (or buying one from the proxy provider) is left to the caller.
Troubleshooting Common Proxy Errors
A proxy authentication popup appearing despite a correctly formatted proxy="user:pass@host:port" string is almost always a Chrome-version issue rather than a credentials issue: confirm SeleniumBase is on a current release (pip install -U seleniumbase), and on very recent Chrome builds where a popup still appears, SeleniumBase's own maintainer guidance is to enable CDP Mode before the first navigation, which routes around the affected extension APIs.
A 407 Proxy Authentication Required that surfaces as a blank page rather than a popup usually means the credentials are wrong or the account's IP allowlist doesn't include the machine's current IP, both of which are worth checking directly in the proxy provider's dashboard before touching test code.
A proxy that connects but returns the wrong exit IP (checked as shown in the verification section above) typically traces back to a malformed proxy string — a stray http:// in front of a socks5://-prefixed value, or a missing port — rather than a broken proxy.
Slow or intermittent responses through a working, correctly authenticated proxy point at the proxy pool itself: bandwidth-capped or overloaded residential exit nodes behave exactly like a slow network rather than like a configuration error.
Teams running the same checks against Playwright instead of SeleniumBase hit a similar shortlist of causes — malformed proxy values, wrong scope, and rejected authentication — since the failure modes come from the proxy layer, not from the specific automation framework on top of it. For teams building their own forward proxy rather than buying gateway access, the tradeoffs around handling both HTTP and HTTPS traffic and enforcing authentication are covered in a separate guide to building a Python proxy server.
Conclusion
SeleniumBase's proxy support comes down to one string format handled consistently across the CLI flag, Driver(), and SB(), with the real complexity hiding in what happens for authenticated proxies on Chrome versus Firefox and in the absence of any automatic rotation between requests. Verifying the exit IP after every proxy change, keeping SeleniumBase current to avoid the Chrome-extension regressions that occasionally land, and picking a proxy gateway that handles session persistence and rotation on its own rather than expecting the test code to do it will cover most of what goes wrong in practice.
Q: Does SeleniumBase support authenticated proxies without a third-party library?
Yes — passing proxy="username:password@host:port" to Driver(), SB(), or the --proxy CLI flag is enough on Chrome and Edge, because SeleniumBase generates its own Manifest V3 extension to answer the proxy's authentication challenge; no proxy-chain-style anonymizing layer is required the way it is with some raw Selenium setups.
Q: Does SeleniumBase's authenticated-proxy support work on Firefox?
No, not the automatic part — Firefox proxy settings go through native network.proxy.* preferences, which cover SOCKS4/5/5h, but SeleniumBase does not inject saved credentials for Firefox, so an authenticated proxy still triggers Firefox's own login prompt.
Q: Can SeleniumBase rotate proxies automatically during a test run?
No — SeleniumBase provides a single-proxy-per-session primitive and a static named PROXY_LIST lookup, but no built-in per-request rotation scheduler; rotating IPs across requests requires either re-launching the driver with a new proxy value or using a proxy gateway that rotates IPs on its own.
Q: Why does a proxy authentication popup appear even with a correct proxy= string?
This is most often a Chrome-version issue: a Chrome 137 change temporarily broke the extension mechanism SeleniumBase uses for proxy authentication, and current SeleniumBase releases include the fix, with CDP Mode as the documented workaround on newer Chrome builds where a popup still surfaces.
Q: Does SeleniumBase support SOCKS5 proxies?
Yes — socks4://, socks5://, and socks5h:// are all valid scheme prefixes in the same proxy string used for HTTP proxies, and authenticated SOCKS5 proxies go through the same Chrome extension auth flow as authenticated HTTP proxies.
Q: Is it safe to run SeleniumBase with a proxy against a site I don't own?
Only if the automation stays within that site's terms of service and applicable law — a proxy changes the exit IP a request is seen from, but it doesn't change whether scraping, account automation, or load against a given target is authorized, so that check belongs before the proxy configuration, not after it.
Ivy Lin
Sep. 24th 2026
110M+ real IPs with 99.9% access success
Blazing-fast average response ~0.5s for high-concurrency tasks
From only $0.1/GB
Get immediate access to premium residential, datacenter, IPv6 and ISP proxy pools.
