NewUnlimited residential proxies: unmetered traffic on a fixed price. From $33.25/day

Python ยท Integration guide

How to use proxies with Selenium

Selenium cannot type into a proxy login prompt, but WebDriver BiDi can answer it for you. This guide uses Python and Firefox to authenticate with Proxonym, hold sticky IPs, target locations and recover from errors.

  • 5 steps
  • 10 min setup
  • Copy-paste code

Before you start

  • Python 3.10 or newer
  • Selenium 4.32 or newer
  • Firefox (Selenium Manager downloads geckodriver automatically)
  • A Proxonym residential or mobile plan
Get proxy credentials

Already a customer? Your username and password are in the dashboard.

  1. Install Selenium

    Selenium 4.32 added the BiDi network handlers used in this guide. Selenium Manager ships with the package and fetches geckodriver on first run, so you only need Firefox installed.

    Shell
    python -m pip install -U selenium
  2. Point Firefox at the gateway and log in

    Set the HTTP and SSL proxy preferences to the gateway, enable BiDi, and register an auth handler. When the gateway sends its 407 challenge, Selenium answers with your username and password.

    Python
    from selenium import webdriver
    from selenium.webdriver.common.by import By
    
    options = webdriver.FirefoxOptions()
    options.enable_bidi = True
    options.set_preference("network.proxy.type", 1)
    options.set_preference("network.proxy.http", "gw.proxonym.com")
    options.set_preference("network.proxy.http_port", 8000)
    options.set_preference("network.proxy.ssl", "gw.proxonym.com")
    options.set_preference("network.proxy.ssl_port", 8000)
    
    driver = webdriver.Firefox(options=options)
    driver.network.add_auth_handler("USERNAME", "PASSWORD")
    
    driver.get("https://api.ipify.org")
    print("Exit IP:", driver.find_element(By.TAG_NAME, "body").text)
    driver.quit()
  3. Keep one IP per browser

    Firefox remembers the proxy login for as long as the browser runs, so treat one driver as one identity. Put a -session- ID in the username to keep every connection on the same IP for up to 120 minutes, and start a new driver when you need a new IP.

    Python
    import secrets
    
    from selenium import webdriver
    
    
    def new_driver(username, language=None):
        options = webdriver.FirefoxOptions()
        options.enable_bidi = True
        options.set_preference("network.proxy.type", 1)
        for scheme in ("http", "ssl"):
            options.set_preference(f"network.proxy.{scheme}", "gw.proxonym.com")
            options.set_preference(f"network.proxy.{scheme}_port", 8000)
        if language:
            options.set_preference("intl.accept_languages", language)
        driver = webdriver.Firefox(options=options)
        driver.network.add_auth_handler(username, "PASSWORD")
        driver.set_page_load_timeout(60)
        return driver
    
    
    session = secrets.token_hex(4)
    driver = new_driver(f"USERNAME-country-us-session-{session}-lifetime-60")
  4. Target a location and match the language

    Add a country, state or city to the username and set the browser language to match. With the new_driver() helper from the previous step, both are one line.

    Python
    from selenium.webdriver.common.by import By
    
    driver = new_driver("USERNAME-country-de-city-berlin-session-b3x9-lifetime-30", language="de-DE, de")
    driver.get("https://ipinfo.io/city")
    print("City:", driver.find_element(By.TAG_NAME, "body").text)
    driver.quit()
  5. Recover from gateway errors

    When the gateway refuses a tunnel, driver.get() raises a WebDriverException that mentions about:neterror. Quit that driver and retry with a new session ID; repeated proxyConnectFailure errors point to wrong credentials.

    Python
    import secrets
    
    from selenium.common.exceptions import WebDriverException
    
    
    def open_with_retry(url, country="us", tries=3):
        for attempt in range(1, tries + 1):
            session = secrets.token_hex(4)
            driver = new_driver(f"USERNAME-country-{country}-session-{session}-lifetime-30")
            try:
                driver.get(url)
                return driver
            except WebDriverException as exc:
                driver.quit()
                print(f"attempt {attempt}:", str(exc).splitlines()[0])
                if attempt == tries:
                    raise
    
    
    driver = open_with_retry("https://example.com")
    print(driver.title)
    driver.quit()

Frequently asked questions

Why not put the credentials in the proxy address?

Browsers ignore a username and password inside proxy settings, and the Selenium proxy capability has no field for HTTP proxy credentials. The gateway therefore answers the first request with a 407 challenge, and the BiDi auth handler replies with your username and password, exactly as a person would in the login prompt.

Can I use Chrome instead of Firefox?

Not with this method today. Chrome ignores credentials in its proxy flag, and its BiDi implementation does not pass proxy login challenges to Selenium, so the handler never fires. For Chromium, drive the browser with Puppeteer or Playwright, which answer proxy logins natively, or use shared datacenter proxies with IP whitelisting, which need no login.

How do I run several IPs in parallel?

Start one driver per identity, each with its own session ID or country in the username, and run them in separate threads, processes or Selenium Grid nodes. Proxonym places no cap on concurrent sessions, so the limits are your machine resources and the pace the target site tolerates.

Does headless Firefox work with the proxy?

Yes. Add the -headless argument to the Firefox options and keep the same proxy preferences and auth handler. Headless mode changes nothing about authentication or targeting, but it does change parts of the browser fingerprint, so keep the language and request pace consistent with the exit location you choose.

Ready to plug it in? Get your credentials.

Pick a plan, copy your username and password from the dashboard and run the code above.

  • Pay as you go
  • Instant activation
  • Crypto accepted
  • 24/7 support