How to use an authenticated proxy with Selenium

Your proxy details

After you buy a plan, open My proxies. Choose the Proxy Type (Rotating or Sticky), the Protocol (HTTP or SOCKS5) and a Format, then copy a line. The generator offers three formats:

In the examples on this page, replace USERNAME, PASSWORD, HOST and PORT with the values from your line. SOCKS5_PORT is the port the generator shows when you pick SOCKS5.

Residential lines are either rotating (a new IP on new connections) or sticky (one IP for the time you choose). Datacenter and ISP plans give you a list of dedicated IPs, one per line as IP:PORT:USERNAME:PASSWORD, and each line is one fixed IP.

To test a line, open https://ipinfo.io/json through it: it shows the exit IP and country. For HTTP lines you can also use the free proxy checker.

Option 1: no password, with an allow-listed IP

If your plan supports login by IP, add your machine’s public IP on the Access & API page. The proxy then needs no password, and plain Selenium is enough. Login by IP is rolling out plan by plan, so check your plan first.

from selenium import webdriver
from selenium.webdriver.common.by import By

options = webdriver.ChromeOptions()
options.add_argument("--proxy-server=http://HOST:PORT")

driver = webdriver.Chrome(options=options)
driver.get("https://ipinfo.io/json")
print(driver.find_element(By.TAG_NAME, "body").text)
driver.quit()

Option 2: a small Chrome extension that answers the login

A Manifest V3 extension can answer the proxy’s login challenge. Put these two files in a folder, for example proxy-auth/.

{
  "manifest_version": 3,
  "name": "Proxy auth",
  "version": "1.0",
  "permissions": ["webRequest", "webRequestAuthProvider"],
  "host_permissions": ["<all_urls>"],
  "background": { "service_worker": "background.js" }
}

chrome.webRequest.onAuthRequired.addListener(
  (details, callback) => {
    if (details.isProxy) {
      callback({ authCredentials: { username: 'USERNAME', password: 'PASSWORD' } });
    } else {
      callback({});
    }
  },
  { urls: ['<all_urls>'] },
  ['asyncBlocking']
);

from selenium import webdriver
from selenium.webdriver.common.by import By

options = webdriver.ChromeOptions()
options.binary_location = "/path/to/chrome-for-testing/chrome"  # see the note below
options.add_argument("--proxy-server=http://HOST:PORT")
options.add_argument("--load-extension=/absolute/path/to/proxy-auth")

driver = webdriver.Chrome(options=options)
driver.get("https://ipinfo.io/json")
print(driver.find_element(By.TAG_NAME, "body").text)
driver.quit()

Note: From version 137, the regular Google Chrome ignores --load-extension. Chrome for Testing and Chromium still support it. Download Chrome for Testing with npx @puppeteer/browsers install chrome@stable and point binary_location at the downloaded chrome binary.

Option 3: selenium-wire

selenium-wire puts its own local proxy between the browser and ZenProxy and sends the credentials for you. It works with Chrome and Firefox, but it was archived in January 2024 and is no longer maintained. It also decrypts and re-encrypts HTTPS traffic with its own certificate, which changes how your traffic looks to sites. Prefer option 1 or 2 for new projects.

pip install selenium-wire "blinker<1.8"

from seleniumwire import webdriver
from selenium.webdriver.common.by import By

seleniumwire_options = {
    "proxy": {
        "http": "http://USERNAME:PASSWORD@HOST:PORT",
        "https": "http://USERNAME:PASSWORD@HOST:PORT",
        "no_proxy": "localhost,127.0.0.1",
    }
}

driver = webdriver.Chrome(seleniumwire_options=seleniumwire_options)
driver.get("https://ipinfo.io/json")
print(driver.find_element(By.TAG_NAME, "body").text)
driver.quit()

The blinker<1.8 pin avoids the No module named 'blinker._saferef' import error that selenium-wire hits with newer blinker releases.

Sticky IPs and rotation

Use sticky lines in browsers. A browser opens many connections for one page, so with a rotating line a single page load can come from several IPs, which breaks logins and looks unnatural. To make sticky lines, open the generator, set Proxy Type to Sticky, choose a Sticky Duration if your plan offers one, set how many lines you want in Sticky Amount, then copy or download them. Each line keeps its IP for the chosen time. The session part of a sticky username differs by plan, so always generate sticky lines instead of editing usernames by hand. A driver keeps its proxy for its whole life, so to change IP, quit the driver and start a new one with another sticky line.

Target a country

On residential plans, add -country- and a two-letter country code to the end of the username, for example USERNAME-country-us or USERNAME-country-gb. To combine a country with a state, a city or a sticky session, build the line in the generator, which shows only the options your plan supports. Datacenter and ISP IPs have a fixed location that you choose when you buy them. With the extension, the country tag goes in the username inside background.js.

Troubleshooting

• Chrome shows a “Sign in” dialog for the proxy

  Nothing is answering the login. Use the extension or selenium-wire, or an allow-listed IP.More on this error →

• The extension doesn’t load

  Regular Chrome 137+ ignores --load-extension. Use Chrome for Testing or Chromium, and pass an absolute folder path.

• ModuleNotFoundError: No module named 'blinker._saferef'

  Install an older blinker: pip install "blinker<1.8".

• net::ERR_TUNNEL_CONNECTION_FAILED

  The proxy refused the CONNECT request. Run the line through curl -v to see the real status (407, 502 or 503).More on this error →

• net::ERR_PROXY_CONNECTION_FAILED

  The browser couldn’t reach the proxy at all. Check the host and port, and that you used the HTTP port for an http:// proxy.More on this error →

Seeing another error? Read proxy errors and how to fix them, or contact support.

Questions