How to Use Proxies with Selenium: Step-by-Step Guide

Prerequisites

Before wiring a proxy into Selenium, make sure the browser stack and proxy credentials are ready. Test the proxy outside Selenium first so you do not debug browser code and proxy auth at the same time.

Step-by-Step Selenium Proxy Setup

This tutorial uses Python, Selenium, and Chrome. Replace the placeholder proxy credentials with your provider endpoint before running the examples.

1. Install Selenium

Create a virtual environment and install Selenium.

python -m venv .venv
.venvScriptsactivate
pip install selenium

2. Configure a Chrome Proxy

For proxies without username/password auth, Chrome can use the proxy server directly through command-line options.

from selenium import webdriver
from selenium.webdriver.chrome.options import Options

proxy_host = "proxy.example.com"
proxy_port = "8000"

options = Options()
options.add_argument(f"--proxy-server=http://{proxy_host}:{proxy_port}")

driver = webdriver.Chrome(options=options)
driver.get("https://api.ipify.org?format=json")
print(driver.page_source)
driver.quit()

3. Add Authentication with an Extension

Chrome does not reliably accept username/password proxy auth directly in --proxy-server. A small extension is the most common workaround.

import zipfile
from pathlib import Path
from selenium import webdriver
from selenium.webdriver.chrome.options import Options

def build_proxy_extension(host, port, username, password, scheme="http"):
    manifest = """
    {
      "version": "1.0.0",
      "manifest_version": 2,
      "name": "ProxyAuth",
      "permissions": ["proxy", "tabs", "unlimitedStorage", "storage", "<all_urls>", "webRequest", "webRequestBlocking"],
      "background": {"scripts": ["background.js"]}
    }
    """
    background = f"""
    chrome.proxy.settings.set({{
      value: {{
        mode: "fixed_servers",
        rules: {{ singleProxy: {{ scheme: "{scheme}", host: "{host}", port: parseInt({port}) }} }}
      }},
      scope: "regular"
    }});
    chrome.webRequest.onAuthRequired.addListener(
      () => ({{ authCredentials: {{ username: "{username}", password: "{password}" }} }}),
      {{ urls: ["<all_urls>"] }},
      ["blocking"]
    );
    """
    plugin_path = Path("proxy_auth_plugin.zip")
    with zipfile.ZipFile(plugin_path, "w") as zp:
        zp.writestr("manifest.json", manifest)
        zp.writestr("background.js", background)
    return str(plugin_path)

options = Options()
options.add_extension(build_proxy_extension(
    "proxy.example.com",
    "8000",
    "username",
    "password",
))

driver = webdriver.Chrome(options=options)
driver.get("https://api.ipify.org?format=json")
print(driver.page_source)
driver.quit()

4. Run Headless Mode with a Proxy

Use Chrome’s newer headless mode and keep proxy configuration identical to headed mode. If a target behaves differently in headless mode, test headed first.

options = Options()
options.add_argument("--headless=new")
options.add_argument("--window-size=1365,768")
options.add_argument("--proxy-server=http://proxy.example.com:8000")

driver = webdriver.Chrome(options=options)
driver.get("https://httpbin.org/ip")
print(driver.page_source)
driver.quit()

5. Rotate Proxies with Selenium

For rotation, start a new browser session per proxy endpoint or per sticky-session credential. Avoid changing proxy state mid-session unless your provider supports it cleanly.

from selenium import webdriver
from selenium.webdriver.chrome.options import Options

proxies = [
    "http://user:pass-session-1@proxy.example.com:8000",
    "http://user:pass-session-2@proxy.example.com:8000",
]

for proxy_url in proxies:
    options = Options()
    options.add_argument(f"--proxy-server={proxy_url}")
    driver = webdriver.Chrome(options=options)
    driver.get("https://api.ipify.org?format=json")
    print(driver.page_source)
    driver.quit()

6. Capture Screenshots for Verification

Save a screenshot after loading a proxy-check page or target page. This makes it easier to prove which exit IP and location were active during the test.

driver = webdriver.Chrome(options=options)
driver.get("https://api.ipify.org?format=json")
driver.save_screenshot("proxy-check.png")
driver.quit()

Anti-Detection Tips

Proxy configuration is only one part of a Selenium workflow. Browser behavior, timing, headers, and session consistency also affect reliability.