October DealsAmazon USOctober deal check: compare before you payAmazon US: current deals, useful picks and tech finds.Check DealsClean PCRecommendedOne scan can reveal what keeps slowing WindowsLook for cleanup and repair opportunities.Run ScanOctober DealsAmazon USDeal season is back - check today's better picksAmazon US: current deals, useful picks and tech finds.See Picks×
Skip to content
World desk4 min

How to Use a Proxy for Each Page in Puppeteer

Puppeteer has no general Page-level proxy setter. Learn how to route by BrowserContext when supported and how to fall back to separate browser processes.
Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

There is no general Puppeteer Page-level proxy setter. A --proxy-server launch argument applies to the browser process; to route pages differently, use separate BrowserContexts with proxyServer where your installed Puppeteer version and browser protocol support it. If they do not, launch a separate browser process for each proxy.

Choose the proxy scope that matches your setup

Method Routing scope When to use it
BrowserContextOptions.proxyServer A BrowserContext and the pages created inside it Use when the installed Puppeteer release and protocol support context-level proxying.
--proxy-server launch argument The browser process Use as a fallback: start a separate browser process for each proxy.

BrowserContexts isolate cookies and cache, create and own their pages, and keep popups opened by a page in that page’s parent context. They are useful for separating page state as well as proxy routes, but do not assume that a browser-wide launch argument can vary between pages.

As an Amazon Associate I earn from qualifying purchases.

Use a different proxy for each BrowserContext

The current Puppeteer Next API reference documents proxyServer and proxyBypassList in BrowserContextOptions. The stable 25.12.0 API reference does not list this option in the same way; the 25.12.0 changelog does describe proxy support for incognito BrowserContexts under BiDi. Confirm that the API exists in your installed release and that your chosen protocol supports it before relying on this pattern.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
import puppeteer from 'puppeteer';

const browser = await puppeteer.launch();

const contextA = await browser.createBrowserContext({
  proxyServer: 'http://proxy-a.example:8080',
});
const pageA = await contextA.newPage();
await pageA.goto('https://example.com');

const contextB = await browser.createBrowserContext({
  proxyServer: 'http://proxy-b.example:8080',
});
const pageB = await contextB.newPage();
await pageB.goto('https://example.com');

await contextA.close();
await contextB.close();
await browser.close();

Replace the example proxy hosts and target URL with endpoints you are authorized to use. To bypass the proxy for selected hosts, use the documented proxyBypassList option only after verifying it is available in your installed version.

#1 Best Overall
GL.iNet GL-MT300N-V2 (Mango) Portable Mini Travel Wireless Pocket VPN WiFi Router - 2X Ethernet Ports | USB 2.0 | OpenWrt | OpenVPN/Wireguard for Public & Hotel Wi-Fi | Easy to Set up via Admin Panel
  • 【WIRELESS MOBILE MINI TRAVEL ROUTER】 Convert a public network (wired or wireless) to a private Wi-Fi for secure surfing. Tethering. Powered by any laptop USB, power banks or 5V/2A DC adapters (sold separately). 39g (1.41 Oz) only, portable and pocket friendly. 2.4GHz ONLY
  • 【OPEN SOURCE & PROGRAMMABLE】 OpenWrt pre-installed, USB disk extendable.
  • 【LARGER STORAGE & EXTENDABILITY】 128MB RAM, 16MB Flash ROM, dual Ethernet ports, UART and GPIOs available for hardware DIY.
  • 【OPENVPN CLIENT】 OpenVPN client pre-installed, compatible with 30+ VPN service providers.
  • 【PACKAGE CONTENTS】 GL-MT300N-V2 (Mango) mini router (2-year Warranty), USB cable, Ethernet cable, User Manual. Please update to the latest firmware.

Check the route before scaling up

  1. Check the installed Puppeteer type definitions or release documentation for BrowserContextOptions.proxyServer.
  2. Run a small request from each context to a destination that reports the observed public IP, and verify that each context exits through the intended proxy.
  3. Repeat with the browser protocol and browser version you plan to deploy. Puppeteer documents supported browser versions; align them when investigating routing issues.

Fallback: launch one browser process per proxy

If context-level routing is unavailable or does not work with your release and protocol, set the proxy when launching each browser instance. Each process and its pages then use that process’s proxy configuration.

import puppeteer from 'puppeteer';

const browserA = await puppeteer.launch({
  args: ['--proxy-server=http://proxy-a.example:8080'],
});
const pageA = await browserA.newPage();
await pageA.goto('https://example.com');

const browserB = await puppeteer.launch({
  args: ['--proxy-server=http://proxy-b.example:8080'],
});
const pageB = await browserB.newPage();
await pageB.goto('https://example.com');

// Close the pages or browsers when their work is complete.
await browserA.close();
await browserB.close();

Puppeteer’s launch options accept additional browser command-line arguments. The trade-off is operational: separate processes are easier to reason about when context proxying is unsupported, but require managing more browser instances. The documentation cited here does not establish a universal performance difference.

Rank #2
Sale
UGREEN NAS DXP2800 2-Bay for Advanced Home Users, Remote Workers & Creators
  • 【Advanced Home Data & Media Hub】For advanced home users who need phone backup, file storage, and centralized data management. Centralize family photos, 4K videos, movies, computer backups, and personal files in one place while running multiple apps for home entertainment and everyday data management. Suitable for households with growing digital libraries and multiple NAS use cases.
  • 【Built for Creators, Media Servers & Advanced Apps】Powered by the Intel N100 Quad-Core CPU, 8GB DDR5 RAM, 2.5GbE networking, and dual M.2 NVMe slots, DXP2800 handles large files and heavier workloads with ease. Run Docker, virtual machines, and media server applications compatible with Plex—ideal for content creators, tech enthusiasts, and advanced home users managing 4K videos, RAW photos, personal media libraries, and multiple NAS apps.
  • 【Up to 80TB for Growing Digital Libraries】 Supports up to 80TB of storage using two HDD bays and two M.2 NVMe SSD slots for family photos, movies, RAW photos, 4K videos, work files, and device backups. AI photo management supports recognition of people, objects, scenes, and locations, album organization, and duplicate photo detection. HDDs and SSDs are not included.
  • 【AI-powered Home Surveillance】Turn DXP2800 into a centralized home surveillance hub by connecting compatible network cameras and storing recordings locally on your NAS. AI-powered features include Face Recognition, People Detection, and Pet Detection, helping advanced home users review important events more efficiently while managing home surveillance and personal data in one place.
  • 【One data Center Across Your Devices】Keep files from desktops, laptops, phones, tablets, and other devices together instead of scattered across cloud accounts and external drives. Access, back up, organize, and share data across Windows, macOS, Android, iOS, web browsers, and compatible smart TVs—ideal for creators and advanced home users working across multiple devices.

Handle HTTP proxy authentication separately

For a proxy that uses HTTP authentication, Puppeteer documents page.authenticate({ username, password }). Set credentials on the page before navigation:

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
await page.authenticate({
  username: 'YOUR_PROXY_USERNAME',
  password: 'YOUR_PROXY_PASSWORD',
});
await page.goto('https://example.com');

This is specifically for HTTP authentication; check your proxy’s authentication scheme rather than assuming all proxy credentials work this way. Puppeteer turns request interception on behind the scenes to implement authentication, which may affect performance.

Rank #3
Sale
Synology DS223 Home & Office Backup Hub - Centralize Files, Protect Data & Monitor Property (2-Bay Diskless NAS)
  • One Place for All Your Data - Consolidate scattered files from multiple computers, phones and external drives into one accessible hub with 100% ownership
  • Professional File Collaboration - Share projects with clients, sync documents across teams and maintain version control without Dropbox fees
  • Automated Backup Protection - Set-and-forget backups for Macs, PCs and mobile devices to multiple destinations including cloud and external drives
  • DIY Surveillance System - Transform IP cameras into a professional monitoring solution with motion alerts, recording schedules and remote viewing
  • 2-Year Warranty - Reliable hardware backed by Synology's expert customer support team and ongoing software updates

Troubleshoot proxy routing

  • Different pages appear to share one route: If the proxy was supplied through --proxy-server, it is configured for the browser process. Use supported context-level proxy settings or separate browser processes.
  • proxyServer is missing or rejected: Confirm the installed release’s API and types. The Next reference and stable 25.12.0 reference do not provide identical evidence for this option; test with your actual protocol.
  • A context request does not use its intended proxy: Verify the observed outbound IP with a routing check, then confirm protocol and browser compatibility. Puppeteer’s supported-browser documentation pairs releases with browser versions.
  • Authentication fails: Check that the endpoint uses HTTP authentication and that credentials are correct; page.authenticate() is not documented here as a general solution for every proxy authentication method.
  • Authenticated requests are slower: Account for the request interception Puppeteer enables to implement page.authenticate(); no fixed performance impact is established.

Or skip the browser setup

If your goal is to capture a website rather than control a browser session, ScreenshotNeo is a website screenshot API and MCP server. One GET request returns a PNG, JPEG, WebP or PDF, without requiring you to configure Puppeteer proxies.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com -o shot.webp

See the ScreenshotNeo API documentation for request options. It accepts cookie and consent banners before capture and removes more than 60 known consent platforms, newsletter popups and chat widgets; those steps can be turned off. Bot checks, blank pages, timeouts, failed loads and cache hits are not billed, and responses identify the page verdict and billing status in headers. Its MCP server lets AI agents use take_screenshot, get_page_info and capture_pdf. The free plan includes 1,000 shots per month without a card; paid plans start at $5 for 3,000 shots.

Sign up for ScreenshotNeo’s free plan to get 1,000 screenshots a month with no card.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
Rank #4
Master Vpn - Free Unlimited VPN Proxy Server
  • Unlimited bandwidth, unlimited data.
  • Super-fast VPN and one tap connect.
  • Free worldwide multiple servers.
  • Works with all type of data carries. (Wi-Fi, 4G, LTE, 3G).
  • No registration, sign up needed.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Support on Ko-Fi

Frequently Asked Questions

Can a popup use a different proxy from the page that opened it?

Popups belong to their parent BrowserContext, so they follow that context rather than getting an independent route.

Best Value
Synology DS124 Personal Backup & File Hub - Protect Photos, Secure Home Surveillance (1-Bay Diskless NAS)
  • Complete Phone & Computer Backup - Automatically protect photos, documents and videos from iPhone android, Mac and Windows to one secure location
  • Your Private File Cloud - Access files from anywhere and share large projects with family or clients without relying on expensive cloud subscriptions
  • Smart Home Security Hub - Monitor your home 24/7 with AI-powered surveillance that detects people, vehicles and sends instant alerts
  • 100% Data Ownership - Keep full control of your personal data with multi-platform access and no monthly subscription fees
  • 2-Year Warranty - Reliable hardware backed by Synology's expert customer support team and ongoing software updates

Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.

Leave a Reply

Your email address will not be published. Required fields are marked *

What’s actually slowing this PC down?

Pick the symptom - the matching free tool is one click away.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

More from the Wire

  1. World desk4 min
    How to Spot an AI Voice Scam Before Sending MoneyDon’t rely on how a caller sounds. Pause, call back through a known number, and verify the emergency with another trusted person before sending money.
  2. Mountain View desk4 min
    Google’s SynthID Detector: How to Check AI-Generated Images, Video and AudioGoogle’s SynthID Detector looks for an embedded watermark in supported images, video and audio. Here is what its results do—and do not—show.
  3. Redmond desk20 min
    How to create a link to File or Folder in Windows 11Windows 11 gives you several ways to point to a file or folder without moving or duplicating it. You can create a desktop shortcut,…
Recommended PC Tool
Recommended PC Tool
Outdated Drivers Are Slowing You DownFree scan - exact matches
Windows Errors? Fix Them Before They SpreadFree repair scan

Two free Windows tools

One Free Minute Could Fix That PC

Before you go - each of these free tools takes about a minute and tackles what quietly slows a Windows PC down.

Special offer. View Outbyte info, uninstall instructions, EULA, and Privacy Policy.