How to use an authenticated proxy with Playwright

Your proxy details

After you buy a plan, open My proxies. Choose the Proxy Type (Rotating or Sticky), the Protocol (HTTP or SOCKS5) and a Format, then copy a line. The generator offers three formats:

In the examples on this page, replace USERNAME, PASSWORD, HOST and PORT with the values from your line. SOCKS5_PORT is the port the generator shows when you pick SOCKS5.

Residential lines are either rotating (a new IP on new connections) or sticky (one IP for the time you choose). Datacenter and ISP plans give you a list of dedicated IPs, one per line as IP:PORT:USERNAME:PASSWORD, and each line is one fixed IP.

To test a line, open https://ipinfo.io/json through it: it shows the exit IP and country. For HTTP lines you can also use the free proxy checker.

Node.js

import { chromium } from 'playwright';

const browser = await chromium.launch({
  proxy: {
    server: 'http://HOST:PORT',
    username: 'USERNAME',
    password: 'PASSWORD',
  },
});

const page = await browser.newPage();
await page.goto('https://ipinfo.io/json');
console.log(await page.textContent('body'));

await browser.close();

Python

from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch(proxy={
        "server": "http://HOST:PORT",
        "username": "USERNAME",
        "password": "PASSWORD",
    })
    page = browser.new_page()
    page.goto("https://ipinfo.io/json")
    print(page.text_content("body"))
    browser.close()

One IP per browser context

Contexts have their own cookies and storage, and each can have its own proxy. Give each context a different sticky line to run several sessions from one browser.

import { chromium } from 'playwright';

const browser = await chromium.launch();

// Sticky lines from the generator: same server, different usernames.
const proxies = [
  { server: 'http://HOST:PORT', username: 'STICKY_USERNAME_1', password: 'PASSWORD' },
  { server: 'http://HOST:PORT', username: 'STICKY_USERNAME_2', password: 'PASSWORD' },
];

for (const proxy of proxies) {
  const context = await browser.newContext({ proxy });
  const page = await context.newPage();
  await page.goto('https://ipinfo.io/json');
  console.log(await page.textContent('body'));
  await context.close();
}

await browser.close();

Playwright Test

Set the proxy for every test in playwright.config.ts.

import { defineConfig } from '@playwright/test';

export default defineConfig({
  use: {
    proxy: {
      server: 'http://HOST:PORT',
      username: 'USERNAME',
      password: 'PASSWORD',
    },
  },
});

Sticky sessions

Use sticky lines in browsers. A browser opens many connections for one page, so with a rotating line a single page load can come from several IPs, which breaks logins and looks unnatural. To make sticky lines, open the generator, set Proxy Type to Sticky, choose a Sticky Duration if your plan offers one, set how many lines you want in Sticky Amount, then copy or download them. Each line keeps its IP for the chosen time. The session part of a sticky username differs by plan, so always generate sticky lines instead of editing usernames by hand.

Target a country

On residential plans, add -country- and a two-letter country code to the end of the username, for example USERNAME-country-us or USERNAME-country-gb. To combine a country with a state, a city or a sticky session, build the line in the generator, which shows only the options your plan supports. Datacenter and ISP IPs have a fixed location that you choose when you buy them.

const context = await browser.newContext({
  proxy: { server: 'http://HOST:PORT', username: 'USERNAME-country-de', password: 'PASSWORD' },
});

SOCKS5

Playwright accepts socks5:// servers, but its username and password options are documented for HTTP proxies. Use HTTP lines when you log in with a password.

Use less data

await page.route('**/*', (route) => {
  const type = route.request().resourceType();
  return ['image', 'media', 'font'].includes(type) ? route.abort() : route.continue();
});

Troubleshooting

• net::ERR_TUNNEL_CONNECTION_FAILED

  The proxy refused the CONNECT request. Run the line through curl -v to see the real status (407, 502 or 503).More on this error →

• Error asking you to launch the browser with a global proxy

  Older Playwright versions need a launch proxy before contexts can set their own. Launch with proxy: { server: "http://per-context" }, or upgrade Playwright.

• 407 or a proxy login page

  Check username and password. The country tag belongs in the username.More on this error →

• Different IPs within one session

  Use a sticky line instead of a rotating one.More on this error →

Seeing another error? Read proxy errors and how to fix them, or contact support.

Questions