Authenticated Proxies in undetected-chromedriver: Extension or Local Forwarder
By the ProxyV4 Engineering Team · Updated:
An undetected chromedriver proxy without a login is one flag, --proxy-server=http://IP:PORT, added to uc.ChromeOptions(). A proxy that needs a username and password takes more work, because Chrome refuses credentials in that flag and the patched driver does nothing to change it. The two approaches that hold up are a tiny Manifest V3 extension that answers the auth challenge, and a local forwarder that adds the login for Chrome.
What undetected-chromedriver patches, and what it does not
The undetected-chromedriver package (imported as uc) downloads a matching ChromeDriver, patches out the automation markers that sites commonly look for, and launches Chrome itself with a set of arguments of its own. Everything below the browser, including DNS, TCP connections and proxy handling, is stock Chrome.
That has two consequences. First, every proxy rule that applies to Chrome applies here: one proxy per browser process, no credentials in flags, and no username and password for SOCKS proxies. Second, the package only addresses one class of signals. Sites also weigh IP reputation, request rate, account history and behavior, and none of those are touched by a patched driver. Treat it as a way to avoid being flagged for running WebDriver, not as a pass through any bot check, and keep your automation within each site's terms.
The baseline: a proxy without a login
If your proxy has no password, pass the address as a Chrome argument. The scheme describes how Chrome talks to the proxy, so http:// is correct even though the sites you open are HTTPS.
import undetected_chromedriver as uc
options = uc.ChromeOptions()
options.add_argument('--proxy-server=http://203.0.113.10:8080')
driver = uc.Chrome(options=options)
driver.get('https://api.ipify.org?format=json')
print(driver.find_element('tag name', 'body').text)
driver.quit()Build a fresh ChromeOptions object for every uc.Chrome() call. The package mutates the options it receives and raises an error if you hand the same object to a second driver, which is easy to hit in a loop that starts one browser per proxy.
Why the login cannot go in the flag
Chrome strips user:pass@ from --proxy-server and, when the proxy answers 407, shows a native sign-in dialog that WebDriver cannot reach. The Selenium proxy guide covers this for plain ChromeDriver. Two details are specific to the undetected setup.
Selenium-wire, the usual Python shortcut, does ship a seleniumwire.undetected_chromedriver module, but it works by running a local man-in-the-middle proxy that decrypts and re-encrypts your HTTPS traffic with its own certificate. That changes the TLS handshake the site sees, which works against the reason you chose undetected-chromedriver, and selenium-wire is no longer maintained. Chrome DevTools tricks that answer Fetch.authRequired are another route, but they keep a debugging domain active for the whole session. The extension and the forwarder avoid both trade-offs.
Option 1: a Manifest V3 extension that answers the auth challenge
Current Chrome no longer runs Manifest V2 extensions, so older snippets that use a background.scripts page with webRequestBlocking fail silently. The MV3 version needs the webRequestAuthProvider permission and the asyncBlocking listener option.
Generate the extension per proxy
This helper writes a two-file extension into a temporary folder. The proxy address still comes from --proxy-server; the extension only supplies the login, and only when the challenge comes from a proxy rather than a website.
import json, tempfile, pathlib
def make_auth_extension(user: str, password: str) -> str:
ext = pathlib.Path(tempfile.mkdtemp(prefix='proxy_auth_'))
(ext / 'manifest.json').write_text(json.dumps({
'manifest_version': 3,
'name': 'Proxy auth',
'version': '1.0',
'permissions': ['webRequest', 'webRequestAuthProvider'],
'host_permissions': ['<all_urls>'],
'background': {'service_worker': 'background.js'},
}))
(ext / 'background.js').write_text(f'''
chrome.webRequest.onAuthRequired.addListener(
(details, callback) => {{
if (details.isProxy) {{
callback({{authCredentials: {{username: {json.dumps(user)}, password: {json.dumps(password)}}}}});
}} else {{
callback({{}});
}}
}},
{{urls: ['<all_urls>']}},
['asyncBlocking']
);
''')
return str(ext)Load it into uc, and the Chrome 137 catch
Pass the folder with --load-extension next to the proxy flag. Since version 137, branded Google Chrome ignores --load-extension, while Chromium and Chrome for Testing still honor it. If the extension does not appear, point uc at one of those builds with browser_executable_path and pin version_main to its major version so the driver matches.
import undetected_chromedriver as uc
ext_dir = make_auth_extension('USER', 'PASS')
options = uc.ChromeOptions()
options.add_argument('--proxy-server=http://203.0.113.10:8080')
options.add_argument(f'--load-extension={ext_dir}')
driver = uc.Chrome(
options=options,
# browser_executable_path='/opt/chrome-for-testing/chrome',
# version_main=142,
)An extension is also a visible part of the browser profile. It is harmless for most work, but if you would rather keep the profile clean, or you must run branded Chrome, use the forwarder below.
Option 2: a local forwarder that adds the login
A forwarder is a small proxy on your own machine that accepts connections without a password and passes them to the real proxy with the credentials attached. Chrome sees an ordinary unauthenticated proxy on 127.0.0.1, so no extension and no dialog are involved. The open-source gost tool does this in one line; other forwarders such as pproxy work the same way.
# One forwarder per upstream proxy; bind to loopback only
gost -L http://127.0.0.1:18080 -F http://USER:[email protected]:8080import undetected_chromedriver as uc
options = uc.ChromeOptions()
options.add_argument('--proxy-server=http://127.0.0.1:18080')
driver = uc.Chrome(options=options)Keep the listener on 127.0.0.1, never 0.0.0.0, or anyone on your network can use your paid proxy without a password. Give each upstream its own local port, start the forwarder before the browser, and stop it when the session ends so you do not collect orphaned processes. The same pattern lets Chrome use a SOCKS5 proxy with a login: forward to a socks5:// upstream and keep the local side HTTP.
Where a single-tenant IP fits a stealth-oriented setup
Once the browser stops announcing that it is automated, the IP becomes one of the louder remaining signals. Shared proxy pools often carry history from other users, and an address that changes mid-session looks odd to a site that keeps you logged in. A ProxyV4 private IPv4 or static ISP proxy has one tenant for the whole term and keeps the same address while active and when you renew, so a long-running test account or monitoring profile stays on one consistent IP.
Every proxy speaks HTTP(S) and SOCKS5 with username and password, which suits both options above, and arrives as an ip:port:user:pass line ready for the helper function. The Selenium setup guide covers the non-stealth basics with the same line. Traffic on private IPv4 and static ISP is unmetered, which helps with heavy, image-rich pages.
It is not a fit if a target only accepts mobile carrier addresses, or if you need a different IP per request; ProxyV4 does not sell mobile or rotating proxies. Nor will any IP make a script acceptable to a site whose terms forbid automation. Test one address first, then scale from the live price list.
Confirm the exit IP and look for leaks
Check the address the site sees
Load an IP echo endpoint right after the driver starts and compare it with the proxy line. If you see your own address, the flag was not applied, which usually means the options object was reused or a forwarder was not running yet. The proxy checker confirms the proxy itself works before you blame the browser.
Check WebRTC
WebRTC can reveal a local or public address outside the proxy path. Open the WebRTC leak test in the automated browser. If it shows your real address, set the Chrome preference webrtc.ip_handling_policy to disable_non_proxied_udp through your profile preferences.
Frequently asked questions
Does undetected-chromedriver support proxy authentication natively?
No. It passes your arguments to Chrome, and Chrome does not accept credentials in --proxy-server. Use an auth extension or a local forwarder.
Can I use a SOCKS5 proxy with a password in uc?
Not directly, since Chrome has no SOCKS5 username and password support. Run a local forwarder to the SOCKS5 upstream, or switch the proxy to HTTP mode, which ProxyV4 offers on the same order.
Does the auth extension work in headless mode?
With --headless=new, extensions load as in a normal window. Keep in mind that headless mode is itself easier for sites to spot than a visible browser.
Can I change the proxy without restarting the browser?
Not with --proxy-server, which is fixed at launch. Start a new driver per proxy, or point Chrome at a local forwarder and restart only the forwarder with a different upstream.
Is undetected-chromedriver still maintained?
Releases have slowed and its author has shifted attention to a successor project, so pin a known-good version and test after every Chrome update.
Pair a clean fingerprint with a single-tenant IP
Get a private IPv4 or static ISP proxy that only you use, with HTTP and SOCKS5 login on one line and the same address on renewal.
Compare plans