Playwright has become a popular choice for browser automation, end-to-end testing, and web data collection. Developers use it to control Chromium, Firefox, and WebKit browsers through a single automation framework.
However, some workflows require more than a standard browser connection.
You may need to test a website from another geographic location, run browser tests through a dedicated network connection, or configure different proxy endpoints for separate browser sessions.
This is where a Playwright proxy becomes useful.
Playwright supports both HTTP and SOCKS5 proxies, with options to configure them globally or individually for browser contexts. It also provides built-in username and password authentication for HTTP proxies.
In this guide, you’ll learn how to configure proxies in Playwright using Node.js and Python, understand the differences between HTTP and SOCKS5, handle authentication, verify your connection, and troubleshoot common errors.
What Is a Playwright Proxy?
A Playwright proxy is an intermediary server through which browser traffic is routed during an automation session.
Instead of connecting directly to a website, Playwright sends browser requests through a configured proxy server.
A typical connection looks like this:
Playwright Script
↓
Browser Instance
↓
Proxy Server
↓
Target WebsiteThe target website receives the request through the proxy’s outbound IP address rather than the original network connection.
This setup can support several legitimate workflows:
- Testing website behavior from different geographic locations.
- Checking localized content and regional page variations.
- Running browser automation through a dedicated IP.
- Testing applications under different network conditions.
- Collecting permitted public web data.
- Separating network configurations across browser sessions.
A proxy does not automatically make browser automation undetectable or guarantee access to every website. Its primary role is to control the network route used by the browser.
Why Use a Proxy with Playwright?
There are several reasons developers integrate proxies into Playwright workflows.
1. Geographic Testing
Websites may display different content depending on the visitor’s location.
For example, an ecommerce website might show different product availability, prices, currencies, or shipping options in different countries.
A geographically targeted proxy allows developers to test these variations without physically connecting from every market.
2. Isolated Browser Sessions
When multiple testing environments require different network configurations, proxies can help separate their outbound connections.
For example:
Browser Context A → US Proxy
Browser Context B → UK Proxy
Browser Context C → Japan ProxyThis is useful for testing localized applications or comparing regional website behavior.
3. Stable Network Connections
Some browser workflows involve multiple navigation steps and require a consistent outbound IP throughout the session.
A static ISP proxy or a residential proxy with a sticky session can help maintain that consistency.
4. Controlled Web Data Collection
Developers may use Playwright to inspect public webpages, render JavaScript-heavy content, or collect information from sources where automated access is permitted.
A proxy can provide geographic or application-level network configuration for these workflows.
However, always review the destination website’s access rules and applicable terms before collecting data.
HTTP vs SOCKS5: Which Proxy Protocol Should You Use?
Before configuring a proxy, understand the two protocols supported by Playwright.
| Feature | HTTP Proxy | SOCKS5 Proxy |
|---|---|---|
| Playwright support | Yes | Yes |
| Browser configuration | Built-in | Built-in |
| Username/password parameters | Documented | Do not assume identical support |
| Application compatibility | HTTP-based clients | SOCKS5-compatible clients |
| Common use | Browser automation and testing | General network routing |
| Configuration | http://host:port | socks5://host:port |
HTTP Proxy
HTTP proxies are a straightforward option for Playwright.
They support proxy authentication through the username and password fields in Playwright’s proxy configuration.
For example:
proxy: {
server: 'http://proxy.example.com:8080',
username: 'your_username',
password: 'your_password'
}An important detail: using an HTTP proxy does not mean that the destination website must use HTTP.
An HTTP proxy can tunnel HTTPS website traffic through the CONNECT method.
Therefore, you can configure an HTTP proxy and still navigate to an HTTPS website.
SOCKS5 Proxy
SOCKS5 is a general-purpose proxy protocol that operates independently of HTTP.
Playwright supports SOCKS5 endpoints using the socks5:// scheme.
For example:
proxy: {
server: 'socks5://proxy.example.com:1080'
}However, there is an important authentication distinction.
Playwright’s official documentation explicitly describes its username and password proxy parameters for HTTP proxy authentication. It does not document identical credential handling for authenticated SOCKS5 endpoints.
Consequently, if your SOCKS5 provider requires authentication, verify compatibility with your Playwright version and browser before using it in production.
For authenticated SOCKS5 services that do not work with the built-in configuration, an alternative compatible network setup may be necessary.
Practical recommendation: If you need straightforward username/password authentication in Playwright, start with an HTTP proxy endpoint.
How to Set Up a Proxy in Playwright with Node.js
Let’s start with a basic Node.js configuration.
Step 1: Install Playwright
First, create a project directory:
mkdir playwright-proxy
cd playwright-proxy
npm init -yInstall Playwright:
npm install playwrightInstall the Chromium browser:
npx playwright install chromiumStep 2: Configure an HTTP Proxy
Create a file named proxy-test.js.
Add the following code:
const { chromium } = require('playwright');
async function main() {
const browser = await chromium.launch({
headless: true,
proxy: {
server: process.env.PROXY_SERVER,
username: process.env.PROXY_USERNAME,
password: process.env.PROXY_PASSWORD
}
});
const page = await browser.newPage();
await page.goto('https://example.com');
console.log('Page title:', await page.title());
await browser.close();
}
main().catch(console.error);The configuration contains three important proxy parameters:
server: The proxy endpoint, including its protocol and port.username: The authentication username.password: The authentication password.
Set the environment variables before running the script:
export PROXY_SERVER="http://proxy.example.com:8080"
export PROXY_USERNAME="your_username"
export PROXY_PASSWORD="your_password"Then execute:
node proxy-test.jsIf the proxy endpoint and credentials are correct, Playwright should launch Chromium and navigate to the target page through the configured connection.
Step 3: Verify the Outbound IP
A successful page navigation does not necessarily prove that the proxy is being used.
To check the actual outbound IP, navigate to an IP-check endpoint:
await page.goto('https://api.ipify.org?format=json');
const ip = await page.locator('body').innerText();
console.log('Current outbound IP:', ip);Compare the returned address with the proxy endpoint’s expected exit IP.
This simple test can help identify configuration mistakes before running a larger automation workflow.
How to Configure a Proxy for Python Playwright
Playwright also supports proxy configuration in Python.
If your automation scripts use Python, the following example provides the same functionality.
Step 1: Install Playwright
pip install playwrightInstall Chromium:
playwright install chromiumStep 2: Configure the Proxy
Create a Python file named proxy_test.py.
import os
from playwright.sync_api import sync_playwright
with sync_playwright() as p:
browser = p.chromium.launch(
headless=True,
proxy={
"server": os.environ["PROXY_SERVER"],
"username": os.environ["PROXY_USERNAME"],
"password": os.environ["PROXY_PASSWORD"]
}
)
page = browser.new_page()
page.goto("https://api.ipify.org?format=json")
print("Outbound IP:", page.locator("body").inner_text())
browser.close()Set the environment variables:
export PROXY_SERVER="http://proxy.example.com:8080"
export PROXY_USERNAME="your_username"
export PROXY_PASSWORD="your_password"Run the script:
python proxy_test.pyThe browser should navigate through the configured HTTP proxy and display the resulting outbound IP.
For production applications, keep proxy credentials in environment variables or a secrets manager rather than hardcoding them in your scripts.
Browser-Level vs Browser Context-Level Proxy Configuration
Playwright provides two main ways to configure proxies.
Understanding the difference is important when building applications with multiple browser sessions.
Browser-Level Proxy
You can configure a proxy when launching the browser:
const browser = await chromium.launch({
proxy: {
server: 'http://proxy.example.com:8080',
username: process.env.PROXY_USERNAME,
password: process.env.PROXY_PASSWORD
}
});This configuration applies to the browser’s requests across its contexts.
It is a practical choice when all browser sessions should use the same network connection.
Browser Context-Level Proxy
Alternatively, Playwright allows proxy settings for individual browser contexts.
const browser = await chromium.launch();
const context = await browser.newContext({
proxy: {
server: 'http://proxy.example.com:8080',
username: process.env.PROXY_USERNAME,
password: process.env.PROXY_PASSWORD
}
});
const page = await context.newPage();
await page.goto('https://example.com');
await context.close();
await browser.close();This approach provides greater flexibility when different contexts need different proxy settings.
For example:
| Browser Context | Proxy Location |
|---|---|
| Context A | United States |
| Context B | United Kingdom |
| Context C | Germany |
Each context can have its own browser state and network configuration.
Choose the browser-level option for a shared connection. Alternatively, use context-level settings when the application needs separate proxy configurations.
How to Configure a Proxy in Playwright Test
If you use the Playwright Test runner, you can configure a proxy directly in playwright.config.js.
For example:
const { defineConfig } = require('@playwright/test');
module.exports = defineConfig({
use: {
proxy: {
server: process.env.PROXY_SERVER,
username: process.env.PROXY_USERNAME,
password: process.env.PROXY_PASSWORD
}
}
});This configuration applies to the tests using the selected project configuration.
It is particularly useful for automated testing environments where all tests should run through the same proxy.
You can also configure different projects with different proxy settings when you need to compare browser behavior across environments.
How to Choose the Right Proxy for Playwright
The proxy type matters just as much as the configuration.
Residential, ISP, and datacenter proxies have different characteristics.
| Proxy Type | Main Advantage | Suitable Playwright Workloads |
|---|---|---|
| Residential | Geographic flexibility | Regional website testing |
| Static ISP | Dedicated, consistent IP | Long-running browser sessions |
| Datacenter | Speed and cost efficiency | Technical testing and accessible public pages |
Residential Proxies
Residential proxies are useful when your Playwright workflow requires geographic flexibility.
For example, a developer may need to test how an ecommerce website displays products in different countries.
QuarkIP Residential Proxies support HTTP and SOCKS5, with country, state, and city-level targeting in supported locations.
Sticky sessions are also available for workflows that benefit from retaining the same IP during a browser session.
Explore QuarkIP Residential Proxies for geographic testing and flexible IP selection.
Static ISP Proxies
Static ISP proxies provide dedicated IP addresses associated with Internet Service Providers.
They can be useful when Playwright scripts need:
- A consistent outbound IP.
- Stable browser sessions.
- Predictable network configurations.
- Repeated tests from the same location.
QuarkIP Static ISP Proxies support HTTP and SOCKS5 connections, making them suitable for compatible Playwright configurations.
For authenticated HTTP proxy connections, use the username and password supplied with your proxy credentials.
Explore QuarkIP Static ISP Proxies for dedicated IP options.
Datacenter Proxies
Datacenter proxies are often a practical option for technical testing and workloads where speed and cost efficiency matter.
Potential use cases include:
- Testing browser automation scripts.
- Validating page rendering.
- Checking accessible public webpages.
- Running internal testing environments.
- Automating permitted web workflows.
QuarkIP Datacenter Proxies support HTTP and SOCKS5 protocols.
Explore QuarkIP Datacenter Proxies to learn more.
Common Playwright Proxy Errors and How to Fix Them
Even with a correct configuration, proxy connections can fail.
The following troubleshooting steps can help identify the problem.
1. ERR_PROXY_CONNECTION_FAILED
This error usually indicates that the browser cannot establish a connection to the proxy server.
Check:
- Proxy hostname.
- Port number.
- Protocol scheme.
- Server availability.
- Network connectivity.
For example, if your provider supplies an HTTP endpoint, use:
server: 'http://proxy.example.com:8080'Do not automatically replace http:// with https:// just because the target website uses HTTPS.
2. 407 Proxy Authentication Required
A 407 response indicates that the proxy requires authentication or has rejected the supplied credentials.
Verify:
- Username.
- Password.
- Authentication format.
- Whether the endpoint requires HTTP or SOCKS5.
- Whether your Playwright configuration supports the selected authentication method.
Also, do not confuse httpCredentials with proxy credentials.
In Playwright, httpCredentials handles HTTP authentication requested by the destination website. Proxy authentication belongs in the proxy configuration object.
3. Proxy Timeout
Timeouts can occur when the proxy server is unavailable, the network route is slow, or the endpoint cannot complete the connection.
Test the proxy independently before investigating the browser script.
If necessary, try another supported endpoint and compare connection times.
4. The Outbound IP Does Not Change
If your IP-check request still returns your original IP address, check whether the browser is actually using the intended proxy.
Also review the bypass configuration.
Playwright supports bypassing selected domains. If the IP-check domain appears in that list, its traffic may use the direct connection instead.
5. SOCKS5 Authentication Does Not Work
Playwright supports SOCKS5 proxy servers, but its documented username/password proxy authentication parameters are specifically described for HTTP proxies.
Therefore, an authenticated SOCKS5 endpoint may require a different compatible setup.
When using a commercial proxy with username/password authentication, testing its HTTP endpoint is often the simplest starting point.
Best Practices for Using Proxies with Playwright
A reliable browser automation workflow should include more than a working proxy connection.
Consider the following practices:
Keep credentials secure. Store usernames and passwords in environment variables or a secrets manager.
Choose the right configuration level. Use browser-level proxies for shared network settings and context-level proxies for separate sessions.
Verify the outbound IP. Check the actual exit address before running larger tasks.
Avoid unnecessary IP changes. A consistent session is often easier to troubleshoot than constantly changing network endpoints.
Monitor bandwidth consumption. Browser automation may load images, scripts, videos, and other resources that increase traffic usage.
Respect website access rules. A proxy does not grant permission to access restricted content or bypass a website’s terms.
Test before scaling. Start with one browser, one endpoint, and one target page before increasing concurrency.
FAQ
Does Playwright support proxies?
Yes. Playwright supports HTTP and SOCKS5 proxies through its browser and browser-context configuration options.
How do I add a proxy to Playwright?
Use the proxy option when launching a browser or creating a browser context. Specify the server address and, for supported authenticated HTTP proxies, the username and password.
Can Playwright use SOCKS5 proxies?
Yes. Playwright supports SOCKS5 endpoints using the socks5:// scheme. However, verify compatibility separately if the SOCKS5 service requires authentication.
How do I authenticate a proxy in Playwright?
For HTTP proxies, provide username and password inside the proxy configuration object. Keep these credentials outside publicly shared source code.
Final Thoughts
Configuring a proxy in Playwright is straightforward once you understand the differences between protocols, authentication methods, and browser contexts.
For most authenticated browser automation setups, an HTTP proxy with username and password configuration is a practical starting point.
Meanwhile, SOCKS5 offers another supported connection option when the endpoint and client configuration are compatible.
The proxy type should also match the workload:
- Residential: Geographic testing and flexible IP selection.
- Static ISP: Dedicated IPs and consistent sessions.
- Datacenter: Cost-efficient technical testing and accessible public pages.
Start with a small test, verify the outbound IP, and confirm that the browser uses the expected network route.
By matching the proxy configuration to your actual automation requirements, you can build a more predictable and maintainable Playwright workflow.
PARTNER WITH QUARKIP Publish your content on QuarkIP Sponsored articles, guest posts and contextual link placements for proxy, web scraping, AI and developer audiences. Packages from $80 Start an inquiry →





