How to Use a Proxy with Selenium
Configure a proxy for Selenium 4 browser traffic, distinguish it from Selenium Manager’s proxy, and troubleshoot common setup issues.
To use a proxy with Selenium 4, set the proxy on the browser Options object before creating the WebDriver session. In Python, attach a Selenium Proxy object to options.proxy, then pass those options to the driver. This configures traffic from the browser session. Selenium Manager’s own network proxy is a separate setting.
Selenium describes a proxy as an intermediary for requests between a client and a server. Proxy configuration can help with network traffic capture, backend-call mocking, or access through a network with corporate restrictions. Use an endpoint and routing policy authorized for your environment. Selenium Browser Options
1. Configure a manual proxy in Python
Install Selenium if it is not already available:
python -m pip install seleniumThen create a browser session with a manual HTTP proxy. The hostname below is a placeholder; replace it with the endpoint supplied by your proxy provider or network administrator.
from selenium import webdriver
from selenium.webdriver.common.proxy import Proxy, ProxyType
options = webdriver.ChromeOptions()
options.proxy = Proxy({
"proxyType": ProxyType.MANUAL,
"httpProxy": "proxy.example.test:8080",
})
driver = webdriver.Chrome(options=options)
try:
driver.get("https://example.com/")
print(driver.title)
finally:
driver.quit()The example follows Selenium’s documented Python structure. The endpoint is illustrative, not an operational or tested proxy. Match the proxy type, address, and protocol to your actual service and browser. Selenium’s browser options guide · Python Proxy API
2. Configure a proxy in other Selenium bindings
Java
Selenium’s guide also demonstrates setting a proxy capability through Chrome options. Add the Selenium Java dependency used by your project, then use the following pattern with your real endpoint:
import org.openqa.selenium.Proxy;
import org.openqa.selenium.chrome.ChromeDriver;
import org.openqa.selenium.chrome.ChromeOptions;
public class ProxyExample {
public static void main(String[] args) {
Proxy proxy = new Proxy();
proxy.setHttpProxy("proxy.example.test:8080");
ChromeOptions options = new ChromeOptions();
options.setProxy(proxy);
ChromeDriver driver = new ChromeDriver(options);
try {
driver.get("https://example.com/");
System.out.println(driver.getTitle());
} finally {
driver.quit();
}
}
}Use the Selenium dependency and browser driver setup already appropriate for your Java project. Refer to the official browser options guide for Selenium 4 session options.
JavaScript
With the Selenium JavaScript binding, provide the proxy through Chrome’s command-line arguments when building the browser options. This example uses Chrome’s --proxy-server flag; browser-specific behavior can vary.
const { Builder } = require('selenium-webdriver');
const chrome = require('selenium-webdriver/chrome');
(async function run() {
const options = new chrome.Options()
.addArguments('--proxy-server=http://proxy.example.test:8080');
const driver = await new Builder()
.forBrowser('chrome')
.setChromeOptions(options)
.build();
try {
await driver.get('https://example.com/');
console.log(await driver.getTitle());
} finally {
await driver.quit();
}
})();Install the JavaScript binding in the project with npm install selenium-webdriver and make sure a compatible Chrome/ChromeDriver setup is available. ChromeDriver accepts standard WebDriver capabilities and Chrome-specific options; see the ChromeDriver capabilities reference. Do not assume an argument supported by one browser is portable to another.
3. Choose the right proxy layer
| What needs the proxy? | Configure it here | What it affects |
|---|---|---|
| Requests made by pages in the browser session | Browser Options / WebDriver proxy capability | The browser session’s traffic after WebDriver starts |
| Selenium Manager’s network connections | Selenium Manager configuration, such as --proxy, its proxy config value, or SE_PROXY |
Manager’s own network access, including browser or driver management requests |
These settings are independent. A Manager proxy does not automatically route pages opened by the browser through that proxy. Likewise, a browser proxy does not necessarily let Selenium Manager download or manage a driver when the environment blocks its network requests. See Selenium Manager documentation.
4. Select a proxy mode and protocol
The Python Proxy API exposes several proxy types. The API surface does not guarantee that every field or mode behaves identically across all browsers, drivers, bindings, and versions.
| Proxy type | Use | What to verify |
|---|---|---|
MANUAL |
Set explicit proxy addresses, such as the HTTP example above. | Host, port, protocol, and any separate secure or SOCKS settings required by the browser. |
PAC |
Use a proxy auto-configuration URL when the browser and binding support the requested capability. | PAC URL reachability and browser-specific support. |
SYSTEM |
Use system proxy settings where supported. | Which machine’s system settings the browser process reads and whether those settings are available to the driver. |
AUTODETECT |
Request automatic proxy detection where supported. | Runtime support and the network’s discovery configuration. |
DIRECT |
Request a direct connection without a proxy. | Whether the network permits direct outbound access. |
UNSPECIFIED |
Leave the proxy type unspecified. | How the target browser and driver interpret the resulting capabilities. |
The Python API includes fields for HTTP and SSL proxy addresses, SOCKS address, version and credentials, a PAC URL, and bypass addresses (noProxy). Set only fields that apply to the selected mode and target browser. Consult the Python Proxy API reference and your browser or provider documentation for the exact capability names and support.
HTTP, secure traffic, SOCKS, and bypass rules
- HTTP proxy: Set the HTTP proxy address for the traffic and browser configuration you intend to route. Follow the provider’s scheme and port instructions.
- HTTPS destinations: Browser proxy behavior for secure destinations depends on the browser’s proxy implementation and the capabilities supplied. Check whether your setup expects an SSL proxy field, an HTTP CONNECT proxy, or another provider-specific configuration.
- SOCKS: The Python API exposes SOCKS address, version, and username/password fields. Confirm the browser and binding support the chosen SOCKS version and authentication behavior.
- Bypass list: The API exposes
noProxyaddresses. Use the format expected by the browser and binding, and verify that internal hosts are routed as intended.
Do not assume that embedding a username and password in an HTTP proxy URL works across browser and Selenium combinations. The cited Selenium API lists SOCKS credential fields, but that does not establish a universal HTTP-authentication recipe. Use the proxy provider’s and browser’s instructions, protect secrets, and validate the actual setup.
5. Verify the configuration
- Confirm the endpoint details. Check protocol, hostname, port, proxy mode, and any required bypass or authentication settings with the network administrator or provider.
- Start the WebDriver session. Make sure the proxy is attached to the Options object passed to the driver constructor.
- Open a permitted test page. Use a target you are allowed to access through the proxy.
- Check the expected route. Use an approved diagnostic endpoint or your organization’s network tooling to confirm the request path. This article does not claim a particular external-IP result.
- Test the Manager path separately if startup fails. If the browser or driver cannot be obtained before a session starts, investigate Selenium Manager’s proxy configuration independently.
6. Troubleshoot common failures
| Symptom | Likely cause | What to check |
|---|---|---|
| Driver startup or browser download fails before a session exists | Selenium Manager cannot reach the network through the environment’s required route. | Configure Manager’s own proxy using its documented setting. A browser Options proxy applies to the browser session, not Manager. |
| Browser starts but the page cannot connect | Wrong host or port, incorrect proxy type, unreachable endpoint, or an unsupported protocol combination. | Compare the configured address and protocol with provider or administrator instructions; test reachability from the machine running the browser. |
| Some pages work but secure destinations fail | The proxy or browser configuration does not handle the destination protocol as expected. | Check the provider’s HTTPS/CONNECT requirements and the browser’s expected proxy fields. |
| Authentication prompt, 407 response, or rejected credentials | Authentication is missing or configured in a way unsupported by the current browser and driver combination. | Follow browser- and provider-specific authentication guidance. Do not assume credentials in a URL work universally; keep secrets out of source control and logs. |
| Internal site bypasses the proxy, or a public site unexpectedly does | System proxy behavior or a bypass list is affecting routing. | Review noProxy, system settings, and the browser’s proxy rules. |
| Proxy capability appears ignored | Options were not passed to the driver, the capability format is invalid, or the selected browser/driver version handles it differently. | Verify the constructor receives the configured Options object and consult the binding and browser documentation for that version. |
| Works locally but not in CI | The CI machine has different DNS, firewall, proxy, environment variables, browser, or driver configuration. | Compare the runner’s network policy and runtime versions with the working environment; check both Manager and browser proxy layers. |
7. Reliability, performance, and cost considerations
A proxy adds another network dependency between the browser and the destination. Availability, latency, connection limits, authentication, and destination access depend on the proxy service and network policy; Selenium’s cited documentation does not publish universal performance or reliability figures. For repeatable automation, record the proxy mode and endpoint source in deployment configuration, keep credentials in a secret store, and make failure logs useful without exposing secrets.
Proxy use can affect page load time and which content is reachable. When diagnosing slow or inconsistent runs, compare the same permitted workflow with the expected route and inspect browser and proxy errors. Avoid treating a timeout as proof that the proxy itself is the only cause; destination response, DNS, firewall rules, and page behavior can also matter.
Cost depends on the endpoint or network service you use. No particular proxy provider, price, or performance level is established by the Selenium documentation cited here. For corporate access, start with the organization’s approved proxy; for a separate service, verify its current pricing, limits, authentication method, and permitted use before relying on it.
8. Capture a page without managing Selenium’s browser proxy
If your goal is a page screenshot rather than browser automation, ScreenshotNeo is a website screenshot API and MCP server. It takes a URL and returns a PNG, JPEG, WebP, or PDF. Its screenshot request does not configure a proxy for your Selenium session; use Selenium when you need to control a browser workflow through your own proxy.
Or skip the browser setup
Send one GET request with the target URL. See the ScreenshotNeo API documentation for request options.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpimport requests
r = requests.get(
"https://api.screenshotneo.com/v1/shot",
params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
timeout=90,
)
open("shot.webp", "wb").write(r.content)const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);- Cookie banners are accepted like a visitor, and 60+ known consent platforms, newsletter popups, and chat widgets are removed before the screenshot. Each step can be turned off.
- Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing; response headers identify the page verdict and billing status.
- An MCP server gives AI agents, including Claude, Cursor, and other MCP clients, tools for screenshots, page information, and PDF capture.
- The Free plan includes 1,000 screenshots a month with no card. Paid plans start at $5 for 3,000 screenshots.
Sign up for ScreenshotNeo’s free plan: 1,000 screenshots a month, no card required.
Frequently asked questions
Does a Selenium proxy change the proxy used by my operating system?
A proxy capability configures the WebDriver browser session. It does not, by itself, change the operating system’s global proxy settings.
Can I use a proxy with a remote WebDriver?
Proxy capabilities are part of the session configuration, but the browser runs in the environment managed by the remote WebDriver. Confirm that the endpoint is reachable from that environment and that its browser supports the requested capabilities.
Is Selenium Manager’s proxy setting enough to route page traffic?
No. Manager’s setting is for Manager network access. Configure browser Options separately when browser requests need a proxy.
Which Selenium version does this apply to?
The examples use Selenium 4’s browser Options pattern. Check the current documentation for your binding and browser because support details can change by version.
