SeleniumBase takes a proxy as one string, host:port or user:pass@host:port, in every mode. The string is the easy part. Chrome ignores a login inside its proxy settings, so SeleniumBase answers the proxy's login request itself, and how it does that depends on the mode. Since Google Chrome 142, the stealth modes can no longer load SeleniumBase's login extension, so UC Mode needs CDP Mode for a login. We read every setting on this page in SeleniumBase 4.54.10, released on 18 September 2026, and in its maintainer's answers.
Why would SeleniumBase need a proxy?
UC Mode and CDP Mode change how the browser looks, not where it comes from. On a server, every site still sees a hosting IP. We tested what the address alone changes, on 19 September 2026: plain requests to thirteen sites, twice from our server and twice through a residential line. A residential IP changed the answer at four of them: Zillow, Instagram, Reddit and DuckDuckGo. Indeed, Glassdoor, Amazon and Booking refused both. That test sent plain requests, not a browser. The table per site is on our OpenClaw page.
How do I set a proxy in SeleniumBase?
In pytest, pass the flag:
pytest my_test.py --proxy=USERNAME:PASSWORD@GATEWAY_HOST:GATEWAY_PORT
In code, pass the same string as proxy=. This is Pure CDP Mode, the shape of SeleniumBase's own proxy example:
from seleniumbase import sb_cdp
sb = sb_cdp.Chrome(proxy="USERNAME:PASSWORD@GATEWAY_HOST:GATEWAY_PORT")
sb.goto("https://api.ipify.org/")
print(sb.get_text("body"))
SB(proxy=...) and Driver(proxy=...) take the same string. A few rules apply to it:
- Schemes. Without one, it is an HTTP proxy.
https://,socks4://,socks5://andsocks5h://are accepted too. - Bypass list.
--proxy-bypass-listtakes hosts separated by semicolons, such as*.foo.com. - Bad strings stop the run. A string SeleniumBase cannot parse raises an error by default, so a typo does not send you out on your own IP. Before 4.53.5, single-label hostnames such as a Docker service name were rejected too.
- Firefox. It takes a proxy without a login. The login is for Chromium browsers only.
How does SeleniumBase answer the proxy login?
Each mode answers it its own way:
| Mode | How the login is answered |
|---|---|
| Regular mode, any Chromium browser | a generated extension in downloaded_files/ |
| UC Mode on Google Chrome 142 or newer | only once CDP Mode is on |
| CDP Mode | a DevTools handler on the first tab |
| Firefox | no login at all |
Google Chrome 142 removed --load-extension and the flag that had kept it working. The maintainer's summary: the regular mode works as before, "If using CDP Mode, then CDP handles the special features like Authenticated Proxy", and UC Mode without CDP Mode needs activate_cdp_mode(). open(url) in UC Mode now switches CDP Mode on by itself. Browsers that are not Google Chrome, such as Chromium, Edge or Brave, still load extensions.
Three details come from the code:
- The password sits on disk. The regular mode writes the extension into
downloaded_files/in your working directory, with the username and password in plain text. Keep that folder out of git and off shared machines. - Every login request gets the proxy login. Both the extension and the CDP handler answer every login request, without checking whether the proxy or a website asked. A site that asks for HTTP authentication would be offered your proxy login.
- Watch the characters. CDP Mode cuts the login at the first
@and splits it at:, so a password with either character breaks there.
What about SOCKS5?
SeleniumBase accepts socks5:// and socks5h://, but Chrome takes no login on a SOCKS5 proxy. The maintainer closes such reports with one line: "Chrome doesn't support direct SOCKS5 authenticated proxies". A SOCKS5 line works only when it needs no login, for example from an allowed IP. For a line with a login, use its HTTP address.
How do I run several proxies at once?
Set multi_proxy=True, or --multi-proxy in pytest. Parallel browsers otherwise reuse one login extension folder, and in the maintainer's words, "they'll overlap and possibly use the same proxy". With it, each browser gets its own folder and its own login.
Which proxy type fits SeleniumBase?
Residential, for the sites that refuse a hosting IP. A test that logs in or fills a cart should keep one IP for the whole flow, so a sticky line fits it. Page-by-page reads suit a rotating line.
HProxy residential gateways fit both, and an allowed IP makes SeleniumBase's login path unnecessary. Allow your server's IP on a Residential Premium plan, up to 150 per plan, and the string is just GATEWAY_HOST:GATEWAY_PORT: no extension, no CDP handler, no password on disk. Rotating ports change the IP, and a sticky port holds one. An allowed IP takes no country or city targeting. For a country, use a generated line: its username carries the targeting, so it goes in the string with the password. A sticky IP can still change early if its device leaves the network, so let the test retry. The residential proxies page lists the plans, and the plan API generates lines and manages allowed IPs from code.
What breaks when the proxy is on?
- The browser asks for the proxy password. UC Mode on Google Chrome 142 or newer, without CDP Mode. Call
activate_cdp_mode(). - Every thread shows the same IP. Set
multi_proxy=True. - "Proxy String ... is NOT in the expected format". The string is malformed. A Docker service name needs 4.53.5 or newer.
- A SOCKS5 line with a login fails. Use the HTTP address instead.
- The login fails with a special password. CDP Mode split it at
@or:. Use an allowed IP or a password without them. - 407 Proxy Authentication Required. On our gateways this means a wrong password or a line from another plan. Our 407 guide walks through it.
- A WebRTC test shows your own IP. A leak on navigations outside the proxy was fixed in 4.51.2. Update.
What this page does not cover
We read SeleniumBase 4.54.10's docs and code, and its maintainer's answers. We did not run SeleniumBase. We did not test whether tabs other than the first get the login in CDP Mode, or what a site sees when it asks for HTTP authentication. The blocking test used plain requests from one server IP and one residential line, over one afternoon. SeleniumBase ships a release almost every day, so we will read these settings again by 19 October 2026.
Where to go from here
How to use proxies in Selenium covers plain Selenium. Proxies for Camoufox and proxies for Scrapling cover two other stealth scraping tools. HTTP vs SOCKS5 explains the two proxy types.
Sources
- Customizing test runs, the proxy options. SeleniumBase documentation, seleniumbase/SeleniumBase release v4.54.10, 18 September 2026.
- proxy_helper.py, settings.py, constants.py, browser_launcher.py, cdp_driver/browser.py and cdp_util.py, and examples/cdp_mode/raw_proxy.py. SeleniumBase source code, release v4.54.10.
- Issue #4179 (the Chrome 142+ changes) and issues #4111, #3847, #4119, #4428, #4488, #4414 and #3843. SeleniumBase issue tracker, 2025 to 2026.
- Proxy support in Chrome: credentials and SOCKSv5. The Chromium Authors, net/docs/proxy.md, read 19 September 2026.
- Plans, IP whitelist and sticky sessions; errors; the proxy API. HProxy documentation, hproxy.com/docs, 19 September 2026.
- Our own test of 19 September 2026: plain GET requests to 13 sites and 3 controls, two runs from our server and two through a residential line of our own house plan, with curl 8.5.0. Raw output is kept in the research folder of our OpenClaw page.
