How to use undetected-chromedriver with a proxy

undetected-chromedriver is a patched version of ChromeDriver. Selenium normally drives Chrome through a driver that leaves recognisable traces, and this library rewrites the parts responsible for the most obvious ones, so an existing Selenium script keeps working while announcing itself less loudly.

It does that by downloading a matching ChromeDriver and patching it at runtime, which is where this failure comes from: the version it picks has to line up with the Chrome you actually have installed, and when it guesses wrong the error it raises describes the symptom rather than the cause.

Installing it

pip install undetected-chromedriver

import undetected_chromedriver as uc

driver = uc.Chrome(headless=True)
driver.get("https://example.com")
driver.quit()

That is the whole API for the common case: it is a drop-in for Selenium's webdriver.Chrome, and everything you already know about options and waits carries over.

On a current Chrome that snippet will not run, which is the section after the proxy call. It fails like this:

selenium.common.exceptions.SessionNotCreatedException: Message: session not
created: cannot connect to chrome at 127.0.0.1:62199
Current browser version is 151.0.7922.175

It names your Chrome version, which is the clue, and then says nothing about it.

When it will not start at all

The two fixes that come up most do not help:

# 1. headless as a library argument rather than a Chrome flag
uc.Chrome(headless=True)                       # FAIL, same error

# 2. the subprocess workaround
uc.Chrome(options=o, use_subprocess=True)      # FAIL, same error

Both failed identically, at a different port each time, which is the giveaway: the driver is starting and Chrome is not staying up long enough to be attached to. Nothing about the process model was the problem.

The fix: pin the Chrome major

import undetected_chromedriver as uc

options = uc.ChromeOptions()
options.add_argument("--headless=new")

driver = uc.Chrome(options=options, version_main=151)   # <- your Chrome major
driver.get("https://example.com")

One argument. version_main tells the library which chromedriver to patch instead of letting it guess, and the guess is what was wrong.

Find your major version with Google Chrome --version, or read it out of the error message you already have: Current browser version is 151.0.7922.175 means version_main=151.

It still does its job once it starts. With the version pinned, navigator.webdriver read false, which is the thing the library exists to do.

Why it will happen again

undetected-chromedriver works by patching a chromedriver binary. That couples it to Chrome's release train, and Chrome ships a new major version every few weeks while the library does not. So the default guess drifts out of date, silently, and the failure surfaces as a connection error rather than a version error.

Pinning is a workaround, not a fix, and you will be back here after your next Chrome update. If that is unappealing, SeleniumBase wraps the same idea and handled Chrome 151 without being told the version, in the same session we ran this:

from seleniumbase import Driver
driver = Driver(uc=True, headless=True)

We measured what each of these tools reports to the page in how to choose an anti-detect browser, where undetected-chromedriver is one of two that would not start unaided.

Adding a proxy

options = uc.ChromeOptions()
options.add_argument("--proxy-server=http://gate.example.com:7000")
driver = uc.Chrome(options=options, version_main=151)

That form takes no username or password, and what happens if you add them is worse than being ignored. We logged the proxy side of this separately: Chrome does not strip the credentials and connect anyway, it fails to parse the value as a proxy at all and our proxy received zero requests. The page then shows a generic "site can't be reached" that names neither a proxy nor authentication.

So for an authenticated proxy the credentials have to come from somewhere other than this flag. The routes that worked in our test are in how to use an authenticated proxy in Selenium; selenium-wire is the one that fits an existing Selenium script. Asking your provider to allowlist your address avoids the question entirely.

Which of those is open to you depends on the provider, and the two ends of it are worth knowing before you pick one. Some providers accept a username and password, some accept only an allowlisted IP, and some accept both. We record what each one states on its provider page, with the date we read it, and say so where a provider states nothing.

The proxy format converter will reshape a credential into the form each client expects, including the separate fields these drivers want rather than a single URL.

Limitations

We did not test whether this evades any particular anti-bot system, and we make no claim that it does. We tested one thing: whether it launches, and what makes it launch when it does not.