Proxy rotation in Selenium or Puppeteer is configured either by pointing the browser at a provider-managed endpoint that rotates for you, or by choosing among proxy endpoints in your own code. These are browser-session settings; they are separate from the proxy Selenium Manager may use to download browsers or drivers. Choose rotation behavior, session persistence, and failure handling deliberately—there is no universal rotation interval.
Know which traffic you are routing
There are two separate network paths to consider:
- Browser-session traffic: Requests made by the page go through the proxy configured for the browser session. Selenium’s WebDriver proxy setting applies here, and Puppeteer can pass proxy settings when it launches Chromium. Selenium documents browser proxying for uses such as capturing network traffic, mocking backend calls, and working with corporate network restrictions. Selenium WebDriver proxy options
- Automation-tool traffic: Selenium Manager may need network access to retrieve a browser or driver. Its proxy configuration applies to Selenium Manager’s own connection, not automatically to the browser session. Selenium Manager proxy configuration
A browser that cannot reach a site and a driver download that cannot complete are different failures. Configure and diagnose the relevant layer rather than assuming one proxy setting covers both.
As an Amazon Associate I earn from qualifying purchases.
Configure a proxy for a Selenium browser session
In Selenium’s JavaScript API, set the proxy on the Chromium options used to create the session. The API also exposes Builder.setProxy(); take care with call order because a later withCapabilities() call can overwrite capabilities already set on the builder. See the JavaScript Chromium Options API and JavaScript Builder API for the current interface.
A representative JavaScript pattern is:
const { Builder, Browser, Proxy } = require('selenium-webdriver');
const chrome = require('selenium-webdriver/chrome');
const proxy = new Proxy({
proxyType: 'manual',
httpProxy: 'proxy.example:8080',
sslProxy: 'proxy.example:8080'
});
const options = new chrome.Options().setProxy(proxy);
const driver = await new Builder()
.forBrowser(Browser.CHROME)
.setChromeOptions(options)
.build();Replace the illustrative hostname and port with the endpoint and protocol supplied by your proxy service. Confirm the exact option shape against the Selenium version you install; the API reference describes the supported interface, while endpoint compatibility and authentication requirements come from the provider.
#1 Best Overall
Keep Selenium Manager’s proxy separate
If Selenium Manager cannot reach the network it needs for browser or driver retrieval, configure its own proxy through --proxy, the proxy configuration value, or the SE_PROXY environment variable. These options affect Selenium Manager’s connection, not the browser’s requests. Selenium Manager documents a default network timeout of 300 seconds; that is a network timeout, not a proxy rotation cadence. Selenium Manager proxy configuration
Configure a proxy for Puppeteer
For browser-session traffic, pass Chromium a proxy server argument at launch. A basic example is:
Rank #2
- Used Book in Good Condition
const browser = await puppeteer.launch({
args: ['--proxy-server=http://proxy.example:8080']
});Use the scheme and endpoint format your provider supports. Proxy authentication is not interchangeable across providers or protocols; follow the provider’s current instructions for credentials. A third-party Puppeteer guide demonstrates using page.authenticate() with proxy credentials, but confirm that approach against the current Puppeteer API and the endpoint’s authentication method before relying on it. Puppeteer rotating-proxy implementation guide
Puppeteer’s configuration documentation lists HTTP_PROXY, HTTPS_PROXY, and NO_PROXY for browser download and runtime proxy settings. Those variables and Puppeteer configuration files are ignored by puppeteer-core. Do not treat a proxy used to download a browser as proof that page traffic is routed through a proxy; verify the launched browser’s configuration and observed egress. Puppeteer configuration
Choose who controls rotation
Rotation can happen at the service endpoint or in your application. The right choice depends on whether you need the service to manage outbound changes or need your code to choose among endpoints. A provider’s own endpoint and session rules are authoritative; no universal rotation cadence or sticky-session behavior is established across providers.
| Approach | What your application does | What you need to manage |
|---|---|---|
| Provider-managed endpoint | Connects to a provider endpoint that changes outbound routing according to that provider’s rules. | Confirm the provider’s rotation trigger, session persistence, protocol, authentication, geography, limits, and failure behavior. |
| Application-managed list | Selects a proxy from configured endpoints, potentially using deterministic selection or tracking. | Manage endpoint health, credentials, session state, retries, and request pacing. A third-party guide describes this pattern but does not establish a generally applicable selection algorithm. Puppeteer rotating-proxy implementation guide |
Before choosing, check whether the workflow needs a stable session across multiple requests or can tolerate changing egress. Also verify supported protocols, concurrency or usage limits, geographic availability, logging and privacy terms, and whether the target permits the automation. Proxy rotation does not itself authorize access or guarantee that requests will succeed.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Understand proxy schemes, bypass rules, and failure behavior
Chromium documents DIRECT, HTTP, HTTPS, SOCKSv4, and SOCKSv5 proxy schemes. Example URI forms include http://foo:2138 and socks5://foo:1080. Its manual configuration can use separate proxy lists for HTTP, HTTPS, and other requests, along with bypass rules. An HTTP proxy tunnels HTTPS using CONNECT: the hostname is sent to the proxy in clear text, while the HTTPS exchange remains encrypted end-to-end through the tunnel. Chromium network settings
Recommended Free Tools
Rank #4
Chrome’s extension API describes modes such as fixed_servers, pac_script, system, direct, and auto-detect, plus per-protocol rules and fallback proxies. These concepts help explain Chrome’s proxy behavior, but they are extension API options—not a requirement to use an extension when configuring Selenium or Puppeteer. Chrome proxy API
If a configured proxy is unreachable, Chromium documents that requests fail with ERR_PROXY_CONNECTION_FAILED unless a fallback is configured. A fallback such as direct:// can send traffic directly instead of through the proxy. Decide whether the authorized workflow should fail closed (stop when the proxy fails) or fail open (allow direct traffic); do not let a fallback silently defeat your routing requirement. Chromium network settings
Quick Recap
Best Value
Diagnose a proxy setup without mixing up failure layers
- Test the endpoint independently. Check that the hostname, port, protocol, and credentials match the provider’s instructions before debugging browser code.
- Verify browser egress. Confirm that a request made by the browser session exits through the expected route; a successful browser or driver download does not prove page traffic uses that route.
- Check scheme and authentication. Make sure the configured proxy scheme is supported and the credential method matches the endpoint. An endpoint that expects a different protocol or authentication mechanism may reject the connection.
- Separate setup from runtime errors. If Selenium cannot retrieve a browser or driver, inspect Selenium Manager’s network proxy. If the browser starts but page requests fail, inspect the WebDriver session or Chromium launch proxy instead.
- Inspect bypass and fallback behavior. Check whether the destination matches a bypass rule and whether a fallback can route traffic directly. Treat a direct fallback as a deliberate policy choice, not just a recovery convenience.
- Review the automation policy. Use automation and proxy routing only for activity permitted by the target and applicable rules; a proxy does not grant permission.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
