Guide

How to Use Mobile Proxies with Playwright

A practical guide to setting a proxy in Playwright with Python and Node.js. Learn how to give each browser context its own mobile proxy, how proxy authentication works, why SOCKS5 with a username and password fails, and how to check the exit IP.

Narmin Kamilsoy
Narmin Kamilsoy Author
10 min read
How to Use Mobile Proxies with Playwright

Playwright is a browser automation framework from Microsoft that drives Chromium, Firefox, and WebKit from Python, Node.js, Java, and .NET. It has proxy support built in, so routing a browser through a mobile proxy takes a few lines of configuration.

This guide shows how to set a proxy for the whole browser and for individual browser contexts, how authentication works, why SOCKS5 with a username and password fails, and how to check which IP your pages actually use. We tested every code sample with Playwright 1.56 and Chromium against a local proxy setup, with the proxy address and URL replaced by a local test server, and the results are summarized at the end.

Before You Start

Install Playwright and a browser. The examples in this guide use Chromium:

Terminal
# Python
pip install playwright
playwright install chromium

# Node.js
npm i -D playwright
npx playwright install chromium

In the examples below, replace proxy-endpoint, the port numbers, user, and pass with the details of your own proxy.

How Playwright Handles Proxies

Playwright takes proxy settings as an object with four fields:

server: the proxy address. According to the Playwright documentation, "HTTP and SOCKS proxies are supported," for example http://myproxy.com:3128 or socks5://myproxy.com:3128. A short form without a scheme is treated as an HTTP proxy.
bypass: an optional comma-separated list of domains that should not use the proxy.
username and password: optional credentials, which the documentation describes as being for when an "HTTP proxy requires authentication."

You can set the proxy in two places. The documentation explains that a proxy "can be either set globally for the entire browser, or for each browser context individually." In Playwright Test, the same object goes under use.proxy in the configuration file.

launch() · Whole browser
●One proxy for every page in the browser
●Set once when the browser starts
●The simplest setup for a single profile
new_context() · Per context
✓Each context gets its own proxy
✓Separate cookies and storage per context
✓Several profiles in one browser

Set a Proxy for the Whole Browser

The simplest setup passes the proxy to launch(). Every page in that browser then uses the same proxy. In Python:

Python
from playwright.sync_api import sync_playwright

PROXY = {
    "server": "http://proxy-endpoint:8000",
    "username": "user",
    "password": "pass",
}

with sync_playwright() as p:
    browser = p.chromium.launch(proxy=PROXY)
    page = browser.new_page()
    page.goto("https://api.ipify.org?format=json")
    print(page.inner_text("body"))
    browser.close()

The same setup in Node.js:

Node.js
const { chromium } = require('playwright');

(async () => {
  const browser = await chromium.launch({
    proxy: {
      server: 'http://proxy-endpoint:8000',
      username: 'user',
      password: 'pass',
    },
  });
  const page = await browser.newPage();
  await page.goto('https://api.ipify.org?format=json');
  console.log(await page.innerText('body'));
  await browser.close();
})();

The page at api.ipify.org returns the IP address it sees, which should be the proxy's exit IP. In our test, Chromium sent the first request without credentials, received a 407 response from the proxy, and then repeated the request with the username and password. This is normal for HTTP proxy authentication and needs no extra code.

1
First request
Chromium sends the request without credentials.
→
2
407 from the proxy
The proxy answers that authentication is required.
→
3
Request repeated
Chromium sends it again with the username and password, and the page loads.

Use a Different Mobile Proxy for Each Browser Context

A browser context is Playwright's isolated session inside one browser. The documentation describes contexts as "isolated clean-slate environments" that are "equivalent to incognito-like profiles," each with its own cookies and storage. Because a context can also have its own proxy, you can run several profiles in one browser, each on its own dedicated mobile proxy port:

Python
from playwright.sync_api import sync_playwright

PORTS = {
    "profile-a": {
        "server": "http://proxy-endpoint:8001",
        "username": "user",
        "password": "pass",
    },
    "profile-b": {
        "server": "http://proxy-endpoint:8002",
        "username": "user",
        "password": "pass",
    },
}

with sync_playwright() as p:
    browser = p.chromium.launch()
    for name, proxy in PORTS.items():
        context = browser.new_context(
            proxy=proxy,
            locale="nl-NL",
            timezone_id="Europe/Amsterdam",
        )
        page = context.new_page()
        page.goto("https://api.ipify.org?format=json")
        print(name, page.inner_text("body"))
        context.close()
    browser.close()

Keep each profile on the same port from run to run. A dedicated port tied to one SIM keeps the profile on that SIM's network, but the IP address can still change after a rotation. Check the rotation settings for the port, log the exit IP at the start of each session, and check it again during long runs.

Keep a profile's session between runs

Using the same proxy port does not keep a session. Each new_context() call starts with an empty context, without the cookies or logins from a previous run. To continue a session, save the context's storage state and load it into the next context for the same profile:

Python
# At the end of a run: save cookies and local storage
context.storage_state(path="profile-a.json")

# In the next run: restore them in a new context on the same port
context = browser.new_context(
    proxy=PORTS["profile-a"],
    storage_state="profile-a.json",
)

Playwright's documentation warns that "the browser state file may contain sensitive cookies and headers," so store these files securely.

Locale and timezone

The example above also sets locale and timezone_id. In our test, a context with locale nl-NL sent the Accept-Language header nl-NL, and the page reported the timezone Europe/Amsterdam. For a Dutch mobile proxy, you can set the browser locale and timezone to Dutch settings when your work requires location-specific browser configuration. Geolocation can be emulated as well, but Playwright's emulation guide sets it together with the geolocation permission. For more on Dutch workflows, see Netherlands Mobile Proxies: A Practical Guide to Dutch Carrier IPs. Rank tracking is covered in Tracking Google.nl Rankings with Mobile Proxies: A Dutch SEO Guide.

SOCKS5 and Authentication

Playwright accepts SOCKS5 proxies, but not with a username and password. In our test, passing credentials with a socks5:// server made both launch() and new_context() fail with the error "Browser does not support socks5 proxy authentication." On Playwright's GitHub, in an issue about this error, a maintainer replied that SOCKS5 proxy authentication is not supported by major browsers or infrastructures. Chromium's own documentation also states that no authentication methods are supported for SOCKSv5 in Chrome.

If your mobile proxy uses a username and password, use its HTTP endpoint in Playwright. With an HTTP proxy, the browser sends the hostname to the proxy, so DNS resolution also happens on the proxy side. Proxy DNS Leaks: How to Check and Prevent Them explains why that matters.

socks5:// with username and password
✕Fails in both launch() and new_context()
✕Error: Browser does not support socks5 proxy authentication
✕Chrome supports no SOCKS5 authentication methods
http:// with username and password
✓Works in launch() and new_context()
✓Chromium answers the 407 challenge itself
✓DNS resolution happens on the proxy side

Lightweight Checks with APIRequestContext

For checks that do not need a full page, Playwright's APIRequestContext sends HTTP requests without a browser and accepts the same proxy option:

Python
from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    request = p.request.new_context(
        proxy={
            "server": "http://proxy-endpoint:8000",
            "username": "user",
            "password": "pass",
        }
    )
    response = request.get("https://api.ipify.org?format=json")
    print(response.status, response.json())
    request.dispose()

In our test, APIRequestContext sent the credentials with the first request and opened a CONNECT tunnel through the proxy, even for an http:// URL. This makes it a quick way to confirm the exit IP before starting browser sessions.

Check the Exit IP

Whatever setup you use, confirm the exit IP from inside the same browser or context. The examples above load api.ipify.org, which returns the IP address it sees. How to Test a Mobile Proxy describes further checks, and Dutch Mobile Carrier IPs: KPN, Odido and Vodafone Explained shows how to identify the carrier behind an exit IP. For browser profiles that also run WebRTC, Mobile Proxies for Antidetect Browsers explains how to check for WebRTC leaks.

What We Saw in a Local Test

We ran the samples above with Playwright 1.56 (Python and Node.js) and Chromium 141 on Linux. A local test site sat behind two HTTP proxies that required a username and password, and each proxy logged the requests it handled, so we could see which proxy each request used. In the code, only the proxy address and the test URL were replaced with local ones.

What we tested What we saw
Chromium, proxy set in launch() with username and password The first request went out without credentials, the proxy answered 407, and Chromium repeated the request with credentials. The page loaded through the proxy.
Chromium, two contexts with different proxies Each context sent its traffic through its own proxy.
Chromium, context with locale nl-NL and timezone Europe/Amsterdam The site received the Accept-Language header nl-NL, and the page reported the timezone Europe/Amsterdam.
Chromium, SOCKS5 proxy with username and password Both launch() and new_context() failed with "Browser does not support socks5 proxy authentication".
APIRequestContext with an HTTP proxy and credentials Credentials were sent with the first request, and the request went through a CONNECT tunnel, even for an http:// URL.
Chromium, context saved with storage_state() and reopened on the same proxy The cookie set in the first context was present in the new context.
Node.js, proxy set in chromium.launch() Same behavior as Python: a 407 first, then the request with credentials.

Common Problems

Symptom Likely cause What to check
Every request returns 407 Proxy Authentication Required Missing or wrong credentials The username and password fields in the proxy option
"Browser does not support socks5 proxy authentication" A SOCKS5 server with username and password Switch to the HTTP endpoint of the same proxy
Requests fail with net::ERR_PROXY_CONNECTION_FAILED or time out Wrong endpoint or port, or the proxy is unreachable Test the same proxy with curl outside Playwright
The exit IP changes during a run The proxy port rotated to a new IP The rotation settings for the port; check the exit IP again during the run, not only at the start

FAQ

Does Playwright support SOCKS5 proxies?

Yes, without authentication. A socks5:// server with a username and password fails with "Browser does not support socks5 proxy authentication." Use the HTTP endpoint of the proxy if it needs credentials.

Can each browser context use a different proxy?

Yes. Pass a proxy object to new_context(), and each context sends its traffic through its own proxy, as our test confirmed.

Do I need extra code for proxy authentication?

No. Put the username and password in the proxy object. Chromium handles the 407 challenge from the proxy and repeats the request with the credentials.

Does the proxy change the browser's language or timezone?

No. The proxy changes the network route and the IP address websites see, not browser settings. Set locale and timezone_id on the context to match the exit location.

Platform terms of service still apply. Running Playwright through a mobile proxy changes how your traffic reaches a website. It does not authorize activity that a platform prohibits.

Related Reading

● 99.9% Uptime ⚡ 4G/5G Carrier SIMs HTTP · SOCKS5 · OpenVPN

Dedicated 4G and 5G Mobile Proxies for Playwright

PowerProxy provides dedicated mobile connections on real carrier SIMs, with HTTP, SOCKS5, and OpenVPN support. In Amsterdam, PowerProxy offers Odido, KPN, and Vodafone SIMs.

✓HTTP, SOCKS5 and OpenVPN
✓A physical modem and SIM reserved for you alone
✓Rotation at set times or via API
✓Odido, KPN and Vodafone SIMs in Amsterdam

No credit card required  ·  4.3 / 5 on Trustpilot ★★★★★  ·  1,200+ businesses

Enjoyed this article? Share it with your network
Narmin Kamilsoy
Written by

Narmin Kamilsoy

Contributing author sharing insights and stories on our blog.

WeChat Telegram