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

Published 2026-11-16 · By Team CleanProxies · [Read on the web](https://www.cleanproxies.com/blogs/chrome-proxy-server)

> Exact chrome --proxy-server syntax for Windows, macOS and Linux, SOCKS5 and DNS, bypass lists and PAC files, and three working ways to use a password-protected proxy, with code we ran.

`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](https://www.cleanproxies.com/products/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):

```bash
# 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):

```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](https://www.cleanproxies.com/integrations/chrome) setup page.

![CleanProxies Google Chrome integration page showing the --proxy-server tip and Static ISP Proxies from $0.75/IP](https://www.cleanproxies.com/media/blog/-P6ZMo-cEK4oKoByCNKX.webp "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](https://chromium.googlesource.com/chromium/src/+/HEAD/net/docs/proxy.md) 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](https://www.chromium.org/developers/design-documents/network-stack/socks-proxy/) 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:

```bash
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](https://www.cleanproxies.com/blogs/socks5h) 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:

```bash
chromium --headless=new --user-data-dir="$(mktemp -d)" \
  --proxy-server="http://USERNAME:PASSWORD@127.0.0.1:8899" \
  --dump-dom "https://api.ipify.org?format=json"
```

Test proxy log while that command ran:

```text
[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:

```bash
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](https://www.cleanproxies.com/tools/what-is-my-ip) (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](https://www.cleanproxies.com/products/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.

![CleanProxies Static ISP Proxies product page hero with Try Now for $4.99 button](https://www.cleanproxies.com/media/blog/-P6ZPGwYQf_oV3GLUE_q.webp "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:

```python
"""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:

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

```text
[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`:

```javascript
// 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:

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

```text
[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:

```javascript
// 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](https://www.cleanproxies.com/integrations/playwright) and [Puppeteer proxy](https://www.cleanproxies.com/integrations/puppeteer) 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`:

```bash
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:

```javascript
function FindProxyForURL(url, host) {
  if (dnsDomainIs(host, ".example.com") || host === "example.com") {
    return "PROXY PROXY_HOST:PROXY_PORT";
  }
  return "DIRECT";
}
```

```bash
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](https://www.cleanproxies.com/tools/what-is-my-ip) 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](https://www.cleanproxies.com/tools/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:

```bash
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](https://www.cleanproxies.com/products/isp-proxies) 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](https://www.cleanproxies.com/pricing).

## FAQs

### Does chrome --proxy-server work on Windows, macOS and Linux?

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.

### Can I put a username and password in --proxy-server?

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.

### Does Chrome support SOCKS5 proxies with 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.

### How do I check that Chrome is using the proxy?

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.

### Why does localhost not go through the proxy?

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.

### Which proxies work with the bare --proxy-server flag?

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.
