Integration · Playwright

Use RoProxy with Playwright

Playwright takes a proxy server, username and password at launch or per browser context, which maps neatly onto RoProxy: every proxy has its own credentials. This guide covers both setups in Node.js and Python, explains why the HTTP port is the one to use with Chromium, runs several IPs in parallel with one proxy per context, and picks the IP mode that keeps a page load consistent.

Use the HTTP port

Chromium does not send a username and password to SOCKS5 proxies: it drops the credentials, the proxy refuses the connection, and the page fails or leaves without the proxy. Proxies from RoProxy always authenticate, so point Chromium at the proxy's HTTP port.

HTTPS sites work through that port: the browser opens a CONNECT tunnel and TLS stays between the browser and the site.

One proxy for the whole browser

import { chromium } from "playwright"

const browser = await chromium.launch({
  proxy: {
    server: "http://GATEWAY_HOST:HTTP_PORT",
    username: "USERNAME",
    password: "PASSWORD",
  },
})
const page = await browser.newPage()
await page.goto("https://api.ipify.org?format=json")
console.log(await page.textContent("body"))
await browser.close()

One proxy per context for parallel IPs

A browser context is an isolated profile with its own cookies. Give each context its own proxy and one browser runs several IPs side by side.

import { chromium } from "playwright"

// Each entry is one proxy, copied from the RoProxy dashboard.
const proxies = [
  { server: "http://GATEWAY_HOST:HTTP_PORT", username: "USERNAME_1", password: "PASSWORD_1" },
  { server: "http://GATEWAY_HOST:HTTP_PORT", username: "USERNAME_2", password: "PASSWORD_2" },
]

const browser = await chromium.launch()
await Promise.all(proxies.map(async (proxy) => {
  const context = await browser.newContext({ proxy })
  const page = await context.newPage()
  await page.goto("https://api.ipify.org?format=json")
  console.log(await page.textContent("body"))
  await context.close()
}))
await browser.close()

Choosing the IP mode for a browser

  • Sticky (bind)

    The default choice for browsers: logins, carts and multi-step flows keep one IP and one cookie jar.

  • Timed rotation

    Good for crawling many pages in a row, as long as no login spans the moment the IP changes.

Common errors

  • net::ERR_TUNNEL_CONNECTION_FAILED

    The gateway host or port is wrong, or the proxy has expired. Check the connection string in the dashboard.

  • 407 or a proxy login prompt

    The username or password is missing or wrong. Pass both in the proxy option, not in the server URL.

  • Slow page loads

    Every resource goes through the proxy. Block images, fonts and media with page.route when you only need the HTML.

Frequently asked questions

Why does the SOCKS5 port not work in Chromium?

Chromium does not send a username and password to SOCKS5 proxies. Use the proxy's HTTP port; HTTPS sites still work through it.

Can each browser context use a different IP?

Yes. Pass each context its own proxy's credentials in newContext({ proxy }); every proxy has its own IP.

Can I change the IP without restarting the browser?

Yes. Call the rotate endpoint of the RoProxy API for that proxy; new connections then leave from the new IP, so open a fresh context to drop old ones.

Related pages

Try it with a free proxy

Verified accounts get limited-time free proxies with random global IPs. No card needed.

Create free account