How to Use a Proxy with Undetected ChromeDriver in 2026
TL;DR
An Undetected ChromeDriver proxy must be configured before Chrome starts. The most dependable path is --proxy-server with an IP-authorized or otherwise non-interactive HTTP, HTTPS, or SOCKS endpoint.
Undetected ChromeDriver does not hide your IP. Its own project description says the package patches Selenium ChromeDriver behavior; network routing remains a separate responsibility.
Chrome does not accept username:password@host:port reliably in --proxy-server. Handle a 407 challenge through a tested CDP authentication flow, a managed local bridge, or provider-side IP authorization.
Restart the browser when changing proxy endpoints. Reusing a driver after changing ChromeOptions does not reroute the existing Chrome process.
Verify route, page status, and expected content separately. A page can load through the intended proxy and still be a login wall, consent page, or soft error.
What Is an Undetected ChromeDriver Proxy?
An Undetected ChromeDriver proxy is a proxy endpoint attached to a Chrome process launched by the Python undetected-chromedriver package. The proxy changes the browser's network route, while the package adjusts selected browser-automation signals. The two functions are complementary but independent.
The current undetected-chromedriver package page lists version 3.5.5 and explicitly warns that the package does not hide an IP address or guarantee results. That boundary is important: using an undetected chromedriver proxy does not make automation invisible, does not bypass access controls, and does not replace permission to access a target.
For authorized localization QA, public-page monitoring, and browser regression tests, a stable route from can keep network identity separate from the browser profile. Treat the proxy, browser profile, cookies, and test account as one stateful session when continuity matters.
How Proxy Routing Works in Undetected ChromeDriver
Proxy routing works at Chrome startup through a command-line argument or a browser-level authentication handler. Undetected ChromeDriver passes compatible Chrome options to the browser; it does not expose a separate high-level proxy API.
Requirement
Recommended mechanism
Operational boundary
HTTP or HTTPS proxy without an interactive login
--proxy-server=http://host:port
Configure before uc.Chrome()
SOCKS5 endpoint
--proxy-server=socks5://host:port
Confirm where DNS is resolved
Username/password proxy
CDP auth handler or a maintained local bridge
Test against the exact Chrome version
Different endpoint per task
New driver per endpoint
Close every old process cleanly
Provider-side rotating gateway
Keep one gateway and vary its documented session policy
Rotation behavior belongs to the provider
Chromium's proxy configuration documentation explains how Chrome maps proxy rules to URL schemes. Selenium's Chrome browser documentation covers Chrome options and browser-version alignment. Keep Chrome, ChromeDriver, Selenium, and the Python package compatible as a group.
Prerequisites
The direct HTTP example was executed with Python 3.12.13, undetected-chromedriver 3.5.5, Selenium 4.47.0, and Chrome 151.0.7922.138. Install the exact browser package first:
Set proxy credentials through a secret manager or protected environment variables. Do not commit a complete proxy URL, print a password, or place secrets in screenshots. Use an authorized target page that returns a route marker or public IP, and cap page-load and script timeouts.
Connect Undetected ChromeDriver Through Nstdata
Create a controlled proxy endpoint, attach it before Chrome starts, and verify the resulting route.
Detailed Tutorial: How to Use an Undetected ChromeDriver Proxy
You can use an Undetected ChromeDriver proxy through four practical patterns: a direct HTTP endpoint, a direct SOCKS5 endpoint, a credential handler, or a bounded browser pool. Start with the simplest route your proxy authentication model supports.
Method 1: Add an HTTP or HTTPS Proxy with ChromeOptions
Use --proxy-server when the endpoint does not require an interactive username/password challenge. This includes an authorized local test proxy and provider endpoints whose access model has already been handled outside Chrome.
import json
import os
import undetected_chromedriver as uc
from selenium.webdriver.common.by import By
defmain(): options = uc.ChromeOptions() options.add_argument(f"--proxy-server={os.environ['PROXY_URL']}") options.add_argument("--headless=new") options.add_argument("--no-first-run") driver = uc.Chrome(options=options, version_main=151, use_subprocess=False)try: driver.set_page_load_timeout(15) driver.get(os.environ["TARGET_URL"]) result = json.loads(driver.find_element(By.ID,"result").text)assert result["route"]== os.environ["EXPECTED_ROUTE"]print(result)finally: driver.quit()if __name__ =="__main__": main()
The executed fixture returned {'route': 'basic-18680', 'authenticated': True, 'target': 'http://fixture.test/items'}. The route assertion proves that Chrome reached the test page through the intended endpoint; the content assertion prevents a successful transport from being mistaken for a useful page.
Do not put http:// inside a separate host field because Chrome expects one complete proxy URI in this flag. The Python proxy configuration and rotation guide provides broader patterns for environment handling and pool design.
Method 2: Configure a SOCKS5 Proxy
Use a socks5:// URI when your proxy endpoint and target workflow require SOCKS5. The browser still receives the setting before launch, so the lifecycle is identical to Method 1.
import os
import undetected_chromedriver as uc
options = uc.ChromeOptions()options.add_argument(f"--proxy-server=socks5://{os.environ['PROXY_HOST']}:{os.environ['PROXY_PORT']}")options.add_argument("--headless=new")driver = uc.Chrome(options=options, version_main=151)try: driver.set_page_load_timeout(15) driver.get(os.environ["TARGET_URL"])print(driver.title)finally: driver.quit()
This block is configuration-verified against the same ChromeOptions path as the live HTTP test; supply a real authorized SOCKS5 endpoint before accepting it in production. Check DNS behavior with a controlled hostname because local versus remote name resolution can change both privacy and failure modes.
Method 3: Handle an Authenticated Proxy with CDP
Use a Chrome DevTools Protocol authentication handler when the proxy responds with HTTP 407 and direct --proxy-server=user:pass@host:port fails. Chrome deliberately separates the proxy address from the authentication exchange.
The following advanced pattern uses Undetected ChromeDriver's documented CDP event listener. It is version-sensitive and must be exercised against the exact Chrome build in staging before use; the current environment verified the event and command schema but could not complete a credentialed browser run.
Never embed credentials in the Python file. If CDP authentication is unstable on your platform, use a maintained local forwarder that authenticates upstream and exposes a loopback-only non-authenticated endpoint to Chrome. Avoid copying Manifest V2 extension snippets: current Chrome extension and command-line policies have changed, so older authentication-extension examples may silently fail.
Method 4: Rotate Proxies by Restarting the Browser
Rotate endpoints by creating one browser per selected proxy and closing it before the next route. ChromeOptions is consumed at process startup; changing the Python object afterward does not reconfigure an existing browser.
import os
import undetected_chromedriver as uc
defrun_one(proxy_url, target_url): options = uc.ChromeOptions() options.add_argument(f"--proxy-server={proxy_url}") options.add_argument("--headless=new") driver = uc.Chrome(options=options, version_main=151)try: driver.set_page_load_timeout(15) driver.get(target_url)return{"proxy": proxy_url,"title": driver.title}finally: driver.quit()pool =[ os.environ["PROXY_URL_A"], os.environ["PROXY_URL_B"],]results =[run_one(proxy, os.environ["TARGET_URL"])for proxy in pool]print(results)
Keep the pool bounded, place unhealthy routes on cooldown, and set a finite retry budget. Do not retry non-idempotent actions such as purchases or form submissions automatically. The web scraping IP rotation guide explains rotation policies, while a provider-side rotating gateway can avoid a new browser for every exit IP when session continuity is not required.
How to Verify the Proxy Without Trusting One Signal
Proxy verification should prove the route, transport result, and page meaning independently. A visible IP change is useful, but it does not establish that the requested content is correct.
Open an authorized IP or route-check endpoint immediately after launch.
Compare its returned route or IP with the expected proxy session.
Confirm a page-specific marker such as a heading, stable ID, or schema field.
Log only a non-secret route ID, timing, status class, and terminal error category.
Use driver.current_url, a stable element, and a small sanitized result object rather than dumping page_source. For recurring errors, the proxy server error troubleshooting guide helps distinguish authentication, timeout, tunnel, and target-response failures.
Common Undetected ChromeDriver Proxy Errors
Undetected ChromeDriver proxy errors usually come from authentication, browser-driver mismatch, DNS, or process lifecycle problems rather than the add_argument() call itself.
Symptom
Likely cause
Fix
ERR_NO_SUPPORTED_PROXIES
Credential-bearing URI or unsupported scheme
Pass only scheme, host, and port; handle auth separately
HTTP 407
Missing or rejected proxy credentials
Verify channel username/password and auth handler
ERR_NAME_NOT_RESOLVED
Proxy not active or DNS path differs
Confirm route first with a controlled hostname
Session not created
Chrome and driver major versions differ
Update the set together or pass the matching version_main
First route works, second does not
Existing Chrome process kept the original proxy
Quit and create a new driver
Page loads but data is wrong
Soft block, login page, or different locale
Add semantic page assertions
Do not respond to detection or access-control failures by increasing volume. Reduce concurrency, inspect terms and authorization, and treat repeated denial as a terminal state.
When Nstdata Fits This Workflow
Nstdata Residential Prime Proxies fit browser workflows that need controlled location and session choices through authenticated proxy endpoints. The main operational challenge is keeping the browser profile, proxy session, and test state aligned, especially when a task spans multiple page loads. Nstdata documents username-based location and session parameters, so a fixed browser route can use either rotating or sticky behavior according to the generated endpoint. The product offers package and pay-per-use billing models, which lets teams choose a model based on expected traffic rather than a universal recommendation. Chrome authentication still needs one of the tested integration paths above; the proxy service does not change Chrome's credential-handling rules.
Session control: Use one documented session identifier for a stateful journey and a new identifier only at a safe task boundary.
Location selection: Generate the required location in the dashboard and validate the observed result instead of inferring geography from a hostname.
Operational fit: Review the current Residential Prime pricing models and select a billing model that matches browser traffic and retry behavior.
Responsible and Reliable Use
Use Undetected ChromeDriver only for authorized testing, public-data workflows, and sites whose terms permit the activity. The word βundetectedβ is a package name, not a promise of invisibility or permission to defeat controls.
Keep concurrency low enough for the target and proxy service, minimize collected data, and retain only what the task requires. Stop on access denial rather than attempting CAPTCHA avoidance, account-ban evasion, or repeated identity switching. Protect credentials in secret storage and redact proxy URLs from logs.
Conclusion
The reliable Undetected ChromeDriver proxy pattern is simple: choose one routing mechanism, configure it before Chrome starts, verify the route, and close the browser before changing endpoints. Direct --proxy-server configuration is the best starting point; credentialed and rotating routes need explicit lifecycle and authentication handling.
Start with one authorized target and one route marker, then add a bounded pool only after the acceptance checks pass. For larger multi-source operations, evaluate Nstdata Proxy Manager for centralized routing and monitoring rather than embedding endpoint logic throughout test code.
Experience Nstdata β Start Your Free Trial Today
Yes. Undetected ChromeDriver accepts Chrome proxy settings through ChromeOptions, including --proxy-server for HTTP, HTTPS, and SOCKS routes supported by Chrome.
Q: Can I put a username and password in the proxy URL?
No reliable cross-version workflow should assume user:password@host:port works in Chrome's --proxy-server argument. Pass the proxy address separately and handle the 407 authentication challenge through a tested CDP flow, maintained local bridge, or provider-supported authorization method.
Q: Why does the proxy work in requests but fail in Chrome?
Chrome and an HTTP client have different proxy and authentication stacks. Check the proxy scheme, DNS path, Chrome's 407 handling, TLS interception policy, and whether the browser loaded a proxy error page.
Q: Can I change the proxy without restarting Undetected ChromeDriver?
Not reliably with startup arguments. Use a provider-side rotating gateway for rotation behind one address, or close the driver and launch a new Chrome process for a different endpoint.
Q: Does undetected-chromedriver prevent blocks?
No. The package changes selected automation signals but gives no guarantee of access, and its official package page states that it does not hide an IP address.
Q: Is using an Undetected ChromeDriver proxy legal?
Using a proxy and browser automation can be lawful, but legality depends on authorization, target terms, data type, jurisdiction, and purpose. Use approved targets, minimize collection, and obtain legal advice for sensitive or regulated workflows.
Kai Watanabe
Sep. 11th 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.
