Skip to content
CleanProxies
Get Started

chrome --proxy-server: Launch Chrome With a Proxy From the Command Line

12 Min Read

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.

Our Google Chrome setup page covers the settings-based route; this post covers the command line. Screenshot: cleanproxies.com/integrations/chrome, 16 Nov 2026.

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):

FormExampleWhat it does
HTTP proxyhttp://PROXY_HOST:8080 or PROXY_HOST:8080No scheme means HTTP; default port 80
HTTPS proxyhttps://PROXY_HOST:443TLS connection to the proxy itself
SOCKS5socks5://PROXY_HOST:1080socks:// also means SOCKS5 here; default port 1080
SOCKS4socks4://PROXY_HOST:1080Resolves 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-serverOverrides 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:8899

Nothing 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.

Static ISP proxies support IP whitelist auth, so the bare --proxy-server flag works without a password. Screenshot: cleanproxies.com/products/isp-proxies, 16 Nov 2026.

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.cjs

We 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

SituationRouteWorks with SOCKS5?
Fixed office/server IP, any launchIP whitelistOnly if your proxy accepts SOCKS5 by whitelisted IP
Occasional manual browsingChrome's login promptNo
Laptop or changing IP, scripted launchesLocal forwarderNo (the forwarder above is HTTP only)
Scripted browser (tests, monitoring)Playwright/Puppeteer loginNo: use an HTTP proxy
Rotating residential or mobile (user:pass only)Forwarder or library loginNo: 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>"
RuleMatches
*.example.comHosts ending in example.com
.example.comSubdomains only
192.168.0.0/16URLs 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:

  1. Open our what is my IP tool in the proxied window; it should show the proxy's IP, not yours.

  2. Check the proxy itself (type, location, response time) with the proxy checker.

  3. Open chrome://net-internals/#proxy to 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

ErrorUsual causeFix
ERR_PROXY_CONNECTION_FAILEDWrong host/port, proxy down, firewallCheck host and port; test with curl first
ERR_NO_SUPPORTED_PROXIESChrome rejected the proxy setting (in our test: credentials inside the proxy URL)Remove USERNAME:PASSWORD@; use whitelist, forwarder or library login
ERR_PROXY_CERTIFICATE_INVALIDhttps:// proxy with a certificate Chrome does not trustUse the proxy's http:// port, or fix the proxy certificate
ERR_TUNNEL_CONNECTION_FAILEDProxy refused the CONNECT (auth, blocked port)Check auth and that the proxy allows port 443
Flag seems ignored, or an old proxy is still usedChrome was already running with that profileClose it, or use a separate --user-data-dir
Local site skips proxyLoopback 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.

Team CleanProxies
Proxy Infrastructure Team
Tags
  • chrome
  • command line
  • proxy setup
  • puppeteer
  • playwright
  • socks5

Related Articles