chrome --proxy-server: Launch Chrome With a Proxy From the Command Line
chrome --proxy-server="http://PROXY_HOST:PROXY_PORT" starts Chrome with its web traffic sent through that proxy instead of the system proxy settings (localhost addresses excepted), and it works the same on Windows, macOS and Linux. The one catch: Chrome refuses a proxy URL that contains USERNAME:PASSWORD@, so a password-protected proxy needs IP whitelist authentication, Chrome's login prompt, a small local forwarder, or a Puppeteer/Playwright login (the scripted routes are below with complete code).
If you want a proxy that works with the bare flag, ISP proxies from CleanProxies (static US IPs, as low as $0.75/IP at 10,000 IPs) support IP whitelist auth for up to 20 IPv4 addresses, so Chrome connects with no password at all.
Quick reference
Linux and macOS (bash or zsh):
# Linux
google-chrome --user-data-dir="$HOME/chrome-proxy-profile" --proxy-server="http://PROXY_HOST:PROXY_PORT"
# macOS
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --user-data-dir="$HOME/chrome-proxy-profile" --proxy-server="http://PROXY_HOST:PROXY_PORT"
# SOCKS5 (hostnames are resolved by the proxy)
google-chrome --user-data-dir="$HOME/chrome-proxy-profile" --proxy-server="socks5://PROXY_HOST:PROXY_PORT" --host-resolver-rules="MAP * ~NOTFOUND , EXCLUDE PROXY_HOST"
# Headless: print the page the target returns (HTML with the JSON inside)
google-chrome --headless=new --user-data-dir="$(mktemp -d)" --proxy-server="http://PROXY_HOST:PROXY_PORT" --dump-dom "https://api.ipify.org?format=json"Windows (PowerShell):
& "C:\Program Files\Google\Chrome\Application\chrome.exe" --user-data-dir="$env:TEMP\chrome-proxy-profile" --proxy-server="http://PROXY_HOST:PROXY_PORT"Replace PROXY_HOST and PROXY_PORT with the values from your proxy dashboard. On Linux the command may be google-chrome-stable, chromium or chromium-browser, depending on how it was installed. For a point-and-click setup (system settings or an extension), see our Chrome proxy setup page.
Why --user-data-dir matters
Chrome reuses a running instance. If Chrome is already open with your normal profile and you start it again with --proxy-server, the new window usually joins the existing process and the flag has no effect. A separate --user-data-dir starts a fresh, isolated instance, so the proxy flag is applied. It also keeps cookies and logins from your main profile out of the proxied session.
--proxy-server syntax
The flag takes a proxy URI. Chromium's proxy documentation lists these forms (read 16 Nov 2026):
| Form | Example | What it does |
|---|---|---|
| HTTP proxy | http://PROXY_HOST:8080 or PROXY_HOST:8080 | No scheme means HTTP; default port 80 |
| HTTPS proxy | https://PROXY_HOST:443 | TLS connection to the proxy itself |
| SOCKS5 | socks5://PROXY_HOST:1080 | socks:// also means SOCKS5 here; default port 1080 |
| SOCKS4 | socks4://PROXY_HOST:1080 | Resolves hostnames locally, IPv4 only |
| Per scheme | "http=PROXY_A:8080;https=PROXY_B:8080" | Different proxy per URL scheme |
| Fallback list | "http://PROXY_HOST:8080,direct://" | Try the proxy, then go direct if it cannot connect |
| No proxy | --no-proxy-server | Overrides every other proxy setting |
Two things to know about fallback lists: only connection failures (the proxy's DNS lookup or TCP connect) trigger the next entry, and a failed proxy is marked bad for about 5 minutes. If you need traffic to stop rather than go out directly when the proxy is down, leave direct:// out.
http:// vs socks5:// and DNS
With socks5://, Chrome sends the hostname to the proxy and the proxy resolves it. Chrome's SOCKS proxy notes add a caveat: --proxy-server covers URL loads, but other parts of the browser (the DNS prefetcher, for example) can still look up names on your local resolver. That is why they recommend:
google-chrome --user-data-dir="$HOME/chrome-proxy-profile" \
--proxy-server="socks5://PROXY_HOST:PROXY_PORT" \
--host-resolver-rules="MAP * ~NOTFOUND , EXCLUDE PROXY_HOST"MAP * ~NOTFOUND stops local DNS lookups, and EXCLUDE PROXY_HOST keeps the one lookup Chrome needs: the proxy's own address. If PROXY_HOST is already an IP address, the exclude is harmless.
The bigger SOCKS5 limit: Chrome supports no authentication for SOCKS5 or SOCKS4. A SOCKS5 proxy that requires a username and password will not work with the bare flag. Use an HTTP proxy with one of the auth routes below, or authorise your machine's IP on the proxy side. If the remote-DNS difference is new to you, our socks5h vs socks5 guide explains it for curl, Python and Node.
Why user:pass in --proxy-server does not work
Chromium's docs say it plainly: Chrome "will not use any credentials embedded in the proxy settings." In practice it goes further. On 16 Nov 2026 we ran Chromium 131 (headless, Linux) against a small local test proxy that requires Basic auth and logs every request it receives:
chromium --headless=new --user-data-dir="$(mktemp -d)" \
--proxy-server="http://USERNAME:[email protected]:8899" \
--dump-dom "https://api.ipify.org?format=json"Test proxy log while that command ran:
[proxy] listening on 127.0.0.1:8899Nothing reached the proxy. Chrome treated the proxy URL with credentials in it as unusable and the page dump contained an error page with "errorCode":"ERR_NO_SUPPORTED_PROXIES". So the request did not leak out directly, but it did not work either. Take the credentials out of the flag and use one of these routes:
IP whitelist on the proxy side (no password at all).
Chrome's login prompt: in a normal (headed) window, Chrome asks for the username and password the first time a password-protected HTTP proxy answers with 407. Fine for manual browsing, useless for headless runs.
A local forwarder that adds the credentials for Chrome.
Puppeteer or Playwright, which answer the login challenge in code.
Route 1: IP whitelist auth (no password needed)
If your proxy provider lets you authorise your own public IP, Chrome needs nothing but the host and port:
google-chrome --user-data-dir="$HOME/chrome-proxy-profile" --proxy-server="http://PROXY_HOST:PROXY_PORT"Find the public IP to whitelist with our what is my IP tool (open it before you add the proxy flag), add it in the proxy dashboard, then launch Chrome. On CleanProxies, IP whitelisting (1-20 IPv4 addresses) is available on ISP and ISP subnet proxies; rotating residential and mobile proxies use username and password only, so use route 2 or 3 for those. This is the cleanest option for a fixed office or server IP, because headless and unattended launches need no login at all.
Route 2: a local forwarder that adds the credentials
When your IP changes (laptop, home connection) or the proxy only takes username and password, run a tiny forwarder on your own machine. This one is for browsing HTTPS sites through an HTTP proxy that uses Basic auth, which covers almost all of today's web. Chrome talks to 127.0.0.1:8888 with no credentials; the forwarder adds the Proxy-Authorization header and passes the traffic to your proxy. Python standard library only:
"""Local forwarder: Chrome talks to 127.0.0.1:8888 with no credentials,
the forwarder adds Proxy-Authorization and passes everything to your proxy."""
import base64, os, select, socket, threading
UPSTREAM = (os.environ.get("PROXY_HOST", "PROXY_HOST"), int(os.environ.get("PROXY_PORT", "8080")))
USERNAME = os.environ.get("USERNAME", "USERNAME")
PASSWORD = os.environ.get("PASSWORD", "PASSWORD")
LISTEN = ("127.0.0.1", 8888)
AUTH = b"Proxy-Authorization: Basic " + base64.b64encode(f"{USERNAME}:{PASSWORD}".encode()) + b"\r\n"
def relay(a, b):
while True:
ready, _, _ = select.select([a, b], [], [], 60)
if not ready:
return
for s in ready:
data = s.recv(65536)
if not data:
return
(b if s is a else a).sendall(data)
def handle(client):
upstream = None
try:
head = b""
while b"\r\n\r\n" not in head:
chunk = client.recv(4096)
if not chunk:
return
head += chunk
first_line, rest = head.split(b"\r\n", 1)
upstream = socket.create_connection(UPSTREAM, timeout=15)
upstream.sendall(first_line + b"\r\n" + AUTH + rest)
relay(client, upstream)
except OSError as err:
print("forwarder error:", err)
finally:
client.close()
if upstream:
upstream.close()
server = socket.socket()
server.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
server.bind(LISTEN)
server.listen(100)
print(f"forwarding {LISTEN[0]}:{LISTEN[1]} -> {UPSTREAM[0]}:{UPSTREAM[1]}")
while True:
conn, _ = server.accept()
threading.Thread(target=handle, args=(conn,), daemon=True).start()Save it as forwarder.py, set the four environment variables to your proxy details, and point Chrome at it:
export PROXY_HOST="your.proxy.host" PROXY_PORT="8080" USERNAME="your-user" PASSWORD="your-pass"
python3 forwarder.py &
google-chrome --user-data-dir="$HOME/chrome-proxy-profile" --proxy-server="http://127.0.0.1:8888"We ran this exact forwarder on 16 Nov 2026 in front of the same password-protected test proxy, with headless Chromium 131. Every request arrived authenticated and the page loaded. Proxy log line and the JSON from the dumped page body (exit IP replaced with a documentation address):
[proxy] CONNECT api.ipify.org:443 proxy-authorization=valid
{"ip":"203.0.113.24"}Notes: Chrome opens every HTTPS site as a CONNECT tunnel, and the forwarder adds the credentials to that first request, so HTTPS sites work. It does not re-authenticate later requests on a reused plain http:// connection, so treat unencrypted HTTP sites as unsupported. It binds to 127.0.0.1 only, so nobody else on your network can use your credentials; keep it running while Chrome is open. The same log also showed Chrome's own background requests (update and account checks) going through the proxy, so count them if you pay per GB.
Route 3: Puppeteer or Playwright login
If you drive Chrome from code, let the library answer the 407 for you.
Playwright takes the credentials in its proxy option. Save this as pw-proxy.cjs:
// pw-proxy.cjs (npm install playwright && npx playwright install chromium)
const { chromium } = require("playwright");
(async () => {
const browser = await chromium.launch({
proxy: {
server: `http://${process.env.PROXY_HOST}:${process.env.PROXY_PORT}`,
username: process.env.USERNAME,
password: process.env.PASSWORD,
},
});
try {
const page = await browser.newPage();
const res = await page.goto("https://api.ipify.org?format=json");
console.log("status", res.status(), "body", await page.textContent("body"));
} catch (err) {
console.error("request failed:", err.message);
process.exitCode = 1;
} finally {
await browser.close();
}
})();Run it with your proxy details in the environment:
PROXY_HOST="your.proxy.host" PROXY_PORT="8080" USERNAME="your-user" PASSWORD="your-pass" node pw-proxy.cjsWe ran this exact file on 16 Nov 2026 (Node 24, Playwright's core package with its bundled Chromium 131) against the same test proxy. Playwright first sent the CONNECT without credentials, got the 407, and retried with them. Output (IP replaced):
[proxy] CONNECT api.ipify.org:443 proxy-authorization=none
[proxy] CONNECT api.ipify.org:443 proxy-authorization=valid
status 200 body {"ip":"203.0.113.24"}Puppeteer passes the flag through args and answers the auth challenge with page.authenticate(). Save as pptr-proxy.cjs and run it the same way (node pptr-proxy.cjs). This one is an example; we did not run it in our test:
// pptr-proxy.cjs (npm install puppeteer)
const puppeteer = require("puppeteer");
(async () => {
const browser = await puppeteer.launch({
args: [`--proxy-server=http://${process.env.PROXY_HOST}:${process.env.PROXY_PORT}`],
});
try {
const page = await browser.newPage();
await page.authenticate({ username: process.env.USERNAME, password: process.env.PASSWORD });
const res = await page.goto("https://api.ipify.org?format=json");
console.log("status", res.status(), "body", await page.evaluate(() => document.body.innerText));
} catch (err) {
console.error("request failed:", err.message);
process.exitCode = 1;
} finally {
await browser.close();
}
})();More options (per-context proxies, sticky sessions) are on our Playwright proxy and Puppeteer proxy pages.
Which auth route to use
| Situation | Route | Works with SOCKS5? |
|---|---|---|
| Fixed office/server IP, any launch | IP whitelist | Only if your proxy accepts SOCKS5 by whitelisted IP |
| Occasional manual browsing | Chrome's login prompt | No |
| Laptop or changing IP, scripted launches | Local forwarder | No (the forwarder above is HTTP only) |
| Scripted browser (tests, monitoring) | Playwright/Puppeteer login | No: use an HTTP proxy |
| Rotating residential or mobile (user:pass only) | Forwarder or library login | No: HTTP(S) only |
--proxy-bypass-list and --proxy-pac-url
--proxy-bypass-list names hosts that should skip the proxy. It only matters together with --proxy-server:
google-chrome --user-data-dir="$HOME/chrome-proxy-profile" \
--proxy-server="http://PROXY_HOST:PROXY_PORT" \
--proxy-bypass-list="*.internal.example;192.168.0.0/16;<local>"| Rule | Matches |
|---|---|
*.example.com | Hosts ending in example.com |
.example.com | Subdomains only |
192.168.0.0/16 | URLs that are literally an IP in that range |
<local> | Hostnames without a dot (intranet names such as fileserver) |
<-loopback> | Removes Chrome's built-in rule that sends localhost direct |
Since Chrome 72, localhost, 127.0.0.1/8 and [::1] always skip a manually set proxy. If you are testing a proxy against a local server, add --proxy-bypass-list="<-loopback>" or your requests will never reach the proxy.
For routing that depends on the URL, use a PAC file instead of --proxy-server. A minimal proxy.pac that sends one site through the proxy and everything else direct:
function FindProxyForURL(url, host) {
if (dnsDomainIs(host, ".example.com") || host === "example.com") {
return "PROXY PROXY_HOST:PROXY_PORT";
}
return "DIRECT";
}google-chrome --user-data-dir="$HOME/chrome-proxy-profile" --proxy-pac-url="https://your-server.example/proxy.pac"In a PAC file PROXY means an HTTP proxy and SOCKS5 host:port means SOCKS5 (plain SOCKS there means SOCKS4).
--proxy-auto-detect (WPAD) is ignored when --proxy-server is set.
Check the exit IP
After launching, confirm the proxy is in use before you do real work:
Open our what is my IP tool in the proxied window; it should show the proxy's IP, not yours.
Check the proxy itself (type, location, response time) with the proxy checker.
Open
chrome://net-internals/#proxyto see the proxy settings Chrome actually applied. Extensions and policies can override what you expect.
From a script, the headless one-liner in the quick reference does the same job: --dump-dom prints the page HTML, with the IP service's JSON inside the body. If Chrome fails and you are not sure whether the proxy or Chrome is at fault, test the proxy alone with curl:
curl -sS --proxy "http://PROXY_HOST:PROXY_PORT" --proxy-user "USERNAME:PASSWORD" "https://api.ipify.org?format=json"Common errors
| Error | Usual cause | Fix |
|---|---|---|
ERR_PROXY_CONNECTION_FAILED | Wrong host/port, proxy down, firewall | Check host and port; test with curl first |
ERR_NO_SUPPORTED_PROXIES | Chrome rejected the proxy setting (in our test: credentials inside the proxy URL) | Remove USERNAME:PASSWORD@; use whitelist, forwarder or library login |
ERR_PROXY_CERTIFICATE_INVALID | https:// proxy with a certificate Chrome does not trust | Use the proxy's http:// port, or fix the proxy certificate |
ERR_TUNNEL_CONNECTION_FAILED | Proxy refused the CONNECT (auth, blocked port) | Check auth and that the proxy allows port 443 |
| Flag seems ignored, or an old proxy is still used | Chrome was already running with that profile | Close it, or use a separate --user-data-dir |
| Local site skips proxy | Loopback bypass rule | --proxy-bypass-list="<-loopback>" |
Running many Chrome profiles
One proxy per profile is the usual setup for QA, ad checks or managing your own accounts: launch each profile with its own --user-data-dir and its own --proxy-server, for example profile-01 with the first IP and profile-02 with the second. Static IPs keep each profile on the same address across sessions, and the ISP plans with IP whitelist let every profile launch without a password. Teams running 100+ profiles can order larger IP lists or whole ISP subnets.
Compare every product and volume tier on the pricing page.
Frequently Asked Questions
Yes. The flag is the same on all three; only the path to the Chrome executable changes. Add a separate --user-data-dir so the flag is applied even when Chrome is already open.
No. Chrome does not use credentials embedded in the proxy URL; in our 16 Nov 2026 test with Chromium 131 the setting was rejected with ERR_NO_SUPPORTED_PROXIES. Use IP whitelist auth, Chrome's login prompt, a local forwarder, or Puppeteer/Playwright authentication.
No. Chrome supports SOCKS5 through --proxy-server="socks5://host:port" but sends no SOCKS username or password. Use IP-based authorization on the proxy side or an HTTP proxy with one of the auth routes in this guide.
Open the CleanProxies what is my IP tool in the proxied window and confirm it shows the proxy's IP, or run Chrome headless with --dump-dom against an IP echo service. chrome://net-internals/#proxy shows the settings Chrome actually applied.
Since Chrome 72, localhost, 127.0.0.1/8 and [::1] always bypass a manually set proxy. Add --proxy-bypass-list="<-loopback>" to send them through the proxy.
Any HTTP proxy that authorizes your IP address instead of a password. CleanProxies ISP and ISP subnet proxies support IP whitelisting for 1-20 IPv4 addresses; rotating residential and mobile proxies use username and password, so pair them with a forwarder or Puppeteer/Playwright.
- chrome
- command line
- proxy setup
- puppeteer
- playwright
- socks5