Proxies for nodriver: browser_args, create_context and the login

nodriver takes a proxy in two places. browser_args=["--proxy-server=..."] sets one for the whole browser, but Chrome ignores a login written into that flag. browser.create_context(url, proxy_server=...) sets one per browser context, and it does handle a username and password, for HTTP and SOCKS5 alike: nodriver starts a small forwarder on your machine that adds the login. The option is marked experimental, and nodriver's README does not mention proxies at all. We read every setting on this page in nodriver 0.50.3, released on 13 May 2026.

Why would nodriver need a proxy?

nodriver changes how Chrome looks to a site, not where it connects from. On a server, every site still sees a hosting IP. We tested what the address alone changes, on 19 September 2026: plain requests to thirteen sites, twice from our server and twice through a residential line. A residential IP changed the answer at four of them: Zillow, Instagram, Reddit and DuckDuckGo. Indeed, Glassdoor, Amazon and Booking refused both. That test sent plain requests, not a browser. The table per site is on our OpenClaw page.

Where does the proxy go in nodriver?

The login decides it:

A proxy without a login, such as a line that allows your server's IP, fits on the command line:

import nodriver as uc

async def main():
    browser = await uc.start(browser_args=["--proxy-server=http://GATEWAY_HOST:GATEWAY_PORT"])
    tab = await browser.get("https://api.ipify.org")

uc.loop().run_until_complete(main())

A proxy with a login goes into a context. Use the tab it returns, not browser.get, which opens pages in the main context without the proxy:

async def main():
    browser = await uc.start()
    tab = await browser.create_context(
        "https://api.ipify.org",
        proxy_server="http://USERNAME:PASSWORD@GATEWAY_HOST:GATEWAY_PORT",
    )

What does create_context do with the login?

When the proxy URL carries a login, three things happen:

1. nodriver starts a forwarder on 127.0.0.1, on a free port, with no login of its own.
2. It opens a new browser context that uses that forwarder as its proxy.
3. The forwarder passes each connection on to your real proxy and adds the login: a Basic Proxy-Authorization header for HTTP, the username and password step for SOCKS5.

Without a login in the URL, no forwarder runs and the address goes straight to Chrome. The forwarder is what makes SOCKS5 with a login possible: Chrome itself supports no SOCKS5 login, but it talks to the forwarder without one. The docstring writes it as socks://USERNAME:PASSWORD@SERVER:PORT, and the maintainer's own example uses socks5://. Both work, because Chrome reads socks:// as SOCKS5.

Each context gets its own proxy. The maintainer's words: "you can even run tabs in different proxies". That is also the way around Chrome's usual limit of one proxy per browser.

Three things to know before you rely on it:

• It is experimental. The docstring marks proxy_server as experimental, and there are failure reports: one user hit ERR_TIMED_OUT with a SOCKS5 proxy, and a 2025 guide from another company could not get it to connect.
• The forwarder has no login. While it runs, any program on the same machine that finds its port can use your proxy through it. On a shared server, an allowed IP is the cleaner route.
• It logs your password. The forwarder logs "which forwards to" with the full proxy URL at info level. nodriver does not set up logging itself, so the line appears as soon as your program logs info messages. logging.getLogger("nodriver").setLevel(logging.WARNING) keeps it out.

Which proxy type fits nodriver?

Residential, for the sites that refuse a hosting IP. A flow that logs in should keep one IP from start to end, so a sticky line fits it. One-off page reads suit a rotating line.

HProxy residential gateways fit both of nodriver's routes. Allow your server's IP on a Residential Premium plan, up to 150 per plan, and the proxy needs no login: browser_args works, no forwarder runs, and no password reaches a log. Rotating ports change the IP, and a sticky port holds one. An allowed IP takes no country or city targeting. For a country, use a generated line: its username carries the targeting, so it goes through create_context. Each generated line has its own sticky session, so one line per context gives each context its own identity. A sticky IP can still change early if its device leaves the network, so let the script retry. The residential proxies page lists the plans, and the plan API generates lines and manages allowed IPs from code.

What breaks when the proxy is on?

• Chrome asks for a login, or the proxy answers 407. The login sits in browser_args. Move it to create_context.
• Pages still come from your own IP. They were opened with browser.get in the main context. Use the tab that create_context returns.
• ERR_TIMED_OUT through create_context. It has been reported with SOCKS5. Try the HTTP address of the same proxy.
• The password shows up in your logs. Set the nodriver logger to WARNING.
• 407 Proxy Authentication Required on our gateways. The password is wrong, or the line belongs to another plan. Our 407 guide walks through it.
• The site still shows a check. A proxy changes the address, not the browser or the way the script acts.

What this page does not cover

We read nodriver 0.50.3's code, and did not run nodriver. We did not measure how reliably the forwarder connects, and we did not check how it handles a percent-encoded password. The blocking test used plain requests from one server IP and one residential line, over one afternoon. nodriver's last release is from May 2026. We will look for a newer one, and read these settings again, by 19 October 2026.

Where to go from here

Proxies for SeleniumBase covers a framework that answers the proxy login in the browser instead. Proxies for Camoufox and proxies for Scrapling cover two other stealth scraping tools. HTTP vs SOCKS5 explains the two proxy types.

Sources

• Browser.create_context, ProxyForwarder, Config and the README. nodriver source code, UltrafunkAmsterdam/nodriver at commit a71cda374651 (version 0.50.3), 13 May 2026.
• Issues #4 and #29. nodriver issue tracker, 2024 to 2026.
• Proxy support in Chrome: credentials and SOCKSv5. The Chromium Authors, net/docs/proxy.md, read 19 September 2026.
• Plans, IP whitelist and sticky sessions; errors; the proxy API. HProxy documentation, hproxy.com/docs, 19 September 2026.
• Our own test of 19 September 2026: plain GET requests to 13 sites and 3 controls, two runs from our server and two through a residential line of our own house plan, with curl 8.5.0. Raw output is kept in the research folder of our OpenClaw page.