Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
Use Chromium’s --proxy-server switch through Pyppeteer’s launch(args=...) option. A minimal HTTP-proxy example is:
import asyncio
from pyppeteer import launch
async def main():
browser = await launch(
args=["--proxy-server=http://proxy.example:8080"]
)
try:
page = await browser.newPage()
await page.goto("https://example.com", {"waitUntil": "networkidle2"})
print(await page.title())
finally:
await browser.close()
asyncio.run(main())Replace the hostname and port with a proxy endpoint you are authorized to use. Pyppeteer does not provide proxy servers; it starts Chromium with command-line arguments, while you supply and operate the endpoint.
What the proxy setting actually does
Pyppeteer passes options to Chromium. The --proxy-server argument tells Chromium where to send traffic, so pages, subresources, WebSockets and downloads follow Chromium’s proxy behavior rather than a Pyppeteer-specific networking layer.
Recommended Free Tools
Chromium documents DIRECT, HTTP, HTTPS, SOCKSv4 and SOCKSv5 schemes. An HTTP proxy can handle HTTP, HTTPS, WebSocket and secure WebSocket URLs. For an HTTPS destination through an HTTP proxy, Chromium creates a CONNECT tunnel; the destination hostname is disclosed to the proxy during tunnel setup. Choose an operator and scheme you trust.
#1 Best Overall
- 【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.
Configure a single proxy
HTTP proxy for all traffic
Use a complete scheme and endpoint:
browser = await launch(args=[
"--proxy-server=http://proxy.example:8080"
])Chromium’s documented equivalent is --proxy-server="http://foo:8080". Keep the argument as one list item. Do not add a fallback unless your application is allowed to connect directly when the proxy is unavailable.
SOCKS proxy
browser = await launch(args=[
"--proxy-server=socks5://proxy.example:1080"
])Use socks4:// or socks5:// only when the endpoint supports that protocol. An HTTPS URL in the argument describes the proxy connection scheme; it does not turn an ordinary HTTP proxy into an HTTPS destination.
Route schemes separately and bypass selected hosts
Chromium supports scheme mappings and bypass rules. A documented mapping pattern is:
--proxy-server="http= https://foo:443;socks=socks5://mysocks:1080"Adapt the syntax carefully to your policy and Chromium version. You can also configure hosts that should bypass the proxy with Chromium’s bypass syntax. Test each URL class you use: page navigation, APIs, WebSockets, service workers and downloads may not take the same path.
Rank #2
- 【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.
Fallback behavior
A fallback such as direct:// allows a direct connection if the proxy cannot be reached. That can improve availability, but it defeats IP or network egress controls. Omit it when every request must remain proxied.
Authenticated proxies: do not embed credentials in the URI
Do not assume that http://user:[email protected]:8080 will authenticate Chromium. Chromium explicitly states that Chrome does not use credentials embedded in manual proxy settings. Authentication proceeds through the browser’s normal credential flow.
Pyppeteer exposes an HTTP authentication method, but the available references do not establish that it works for every proxy scheme or challenge type. If your proxy requires credentials, verify its authentication method with the endpoint and Chromium version you deploy. Keep credentials in environment variables or a secret manager, never in source control, command history or logs.
import os
proxy_user = os.environ["PROXY_USER"]
proxy_password = os.environ["PROXY_PASSWORD"]
# Pass the proxy host with --proxy-server, then verify the
# proxy's challenge flow against the Pyppeteer version you use.
If the proxy uses a non-HTTP challenge, a browser extension or a proxy-side allowlist may be required; Pyppeteer’s documented authenticate API alone is not proof of compatibility.
Rank #3
- 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
A complete reusable Pyppeteer script
import asyncio
import os
from pyppeteer import launch
async def capture(url: str) -> str:
proxy = os.environ.get("PROXY_SERVER", "http://proxy.example:8080")
browser = await launch(
headless=True,
args=[
f"--proxy-server={proxy}",
"--no-sandbox", # Use only where your container policy permits it.
],
)
try:
page = await browser.newPage()
await page.setViewport({"width": 1366, "height": 768})
await page.goto(url, {"waitUntil": "networkidle2", "timeout": 60000})
return await page.title()
finally:
await browser.close()
async def main():
print(await capture("https://example.com"))
if __name__ == "__main__":
asyncio.run(main())Install Pyppeteer in the environment used by the script, and ensure its Chromium executable is available. The project says Python 3.8 or later is required. On first use, it may download Chromium if a suitable browser is missing; the project estimates that download at about 150 MB (year not stated).
Verify that traffic is really proxied
- Start with a harmless page you control or an IP-display endpoint approved for your testing.
- Run the script with
PROXY_SERVERset to the exact scheme, host and port. - Compare the observed egress address and headers with a direct browser run.
- Test an HTTPS page, a redirect, a page that loads subresources and any WebSocket or API operation your application needs.
- Check proxy logs and Chromium errors without recording usernames, passwords or session cookies.
A successful page load alone does not prove that every resource used the proxy; service workers, extensions and operating-system traffic can have separate behavior.
Common failures and fixes
“ERR_PROXY_CONNECTION_FAILED” or immediate timeouts
- Confirm DNS resolution and that the port is reachable from the machine running Chromium.
- Check that the scheme matches the endpoint (HTTP versus SOCKS).
- Remove an accidental
direct://fallback when direct access is prohibited. - Increase
page.gototimeout only after fixing reachability; a longer timeout cannot repair a closed port.
HTTPS pages fail through an HTTP proxy
HTTPS requires the proxy to permit CONNECT tunneling. Ask the operator whether the endpoint supports the destination port and CONNECT method. Do not replace the destination URL with HTTP merely to hide the error.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Proxy authentication loops or 407 responses
The endpoint is demanding authentication that Chromium has not satisfied. Credentials embedded in --proxy-server are not a solution. Confirm the challenge type, test Pyppeteer’s HTTP authentication flow for that exact endpoint, and consider an authenticated gateway or IP allowlisting.
Rank #4
- 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.
Some requests bypass the proxy
Inspect scheme mappings, bypass rules, service-worker behavior and any separate process making requests. Remove broad bypass patterns and test redirects and WebSockets independently.
Chromium will not start in a container
Provide a compatible executable and required libraries. The --no-sandbox switch is a deployment decision with security implications, not a universal fix; use it only when your container isolation policy explicitly permits it.
It worked yesterday, then broke
Record the Pyppeteer release, Chromium revision, proxy scheme and endpoint policy. Pyppeteer’s repository describes the project as unmaintained, so browser-version drift and unresolved compatibility issues are real maintenance risks.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →Pyppeteer maintenance versus Playwright Python
Pyppeteer is an unofficial Puppeteer port, and its own project description warns that it is unmaintained. Existing Pyppeteer code may still be practical when you control the browser revision and only need launch arguments, but budget time for dependency and Chromium compatibility work.
Best Value
- 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
The project recommends considering Playwright Python. Playwright’s Python network documentation exposes a structured proxy configuration with a server plus optional username and password, globally at browser launch or per browser context. That is a different API from Pyppeteer’s command-line approach, not a drop-in replacement. Compare:
| Question | Pyppeteer | Playwright Python |
|---|---|---|
| Project status | Repository describes it as unmaintained. | Official Python network guide documents proxy configuration. |
| Proxy configuration | Chromium --proxy-server in launch(args=...). |
Structured server option at launch or context level. |
| Credential fields | Not established as universally supported through the proxy argument; verify challenge handling. | Proxy configuration includes optional username and password fields. |
| Migration cost | Lowest when your existing automation already depends on Pyppeteer. | Requires API and selector migration, but may simplify new proxy-aware projects. |
Choose based on your existing code, required authentication, browser versions and deployment support—not on the assumption that either library supplies a proxy service.
Performance, privacy and operating costs
- Latency: Every request adds a hop; distant proxy regions and overloaded endpoints increase navigation time.
- Capacity: Concurrency limits, bandwidth quotas and connection limits belong to the proxy service. Confirm them before scaling workers.
- Reliability: Decide whether a failed proxy should fail the job or permit direct access. Encode that decision explicitly; do not silently leak traffic.
- Privacy: The proxy can observe destination hostnames and, depending on configuration, request metadata. Use HTTPS and a trusted operator.
- Resource use: Headless Chromium is heavier than an HTTP client. Reuse a browser process where safe, create pages deliberately, and always close the browser in a
finallyblock.
Or skip the browser setup
For a clean image or PDF of a public page, ScreenshotNeo is a website screenshot API and MCP server. It accepts a URL in one request and handles browser capture for you. The cURL call is:
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the complete parameter list and response behavior in the ScreenshotNeo documentation. Python and Node.js equivalents:
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);ScreenshotNeo removes cookie-consent banners, newsletter popups and chat widgets before capture. Bot checks, blank pages, failed loads and cache hits are not billed, and response headers identify the page verdict and billing status. Its MCP server provides take_screenshot, get_page_info and capture_pdf tools for Claude, Cursor and other MCP clients. The Free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000. Create a free ScreenshotNeo account.
Frequently Asked Questions
Does Pyppeteer include a proxy server?
No. It launches Chromium with your supplied proxy endpoint; you must obtain and authorize the proxy service separately.
Can one browser use different proxies for different pages?
The basic Pyppeteer method applies the proxy at Chromium launch. Separate browser processes are the straightforward isolation option; verify any lower-level Chromium approach against your deployment.
Should I add direct:// as a fallback?
Only when direct connections are explicitly acceptable. Otherwise it can bypass the network policy the proxy was meant to enforce.
Quick Recap
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.
