Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
Direct answer: install Pyppeteer in the Python environment that has access to your package index, download Chromium through the same network if needed, then pass Chromium’s --proxy-server flag in launch(args=[...]). These are separate network paths: proxy settings for pip do not automatically route pages opened by Chromium.
The procedure below covers a clean virtual-environment setup, authenticated-network edge cases, an existing browser binary, proxy syntax, diagnostics, and an API alternative when you do not need to manage a browser.
What “behind a proxy” means in Pyppeteer
There are three connections to account for:
- Python package installation:
python3 -m pip install pyppeteercontacts your package index. Configure this path with the proxy environment used by your operating system or package tooling, commonlyHTTP_PROXYandHTTPS_PROXY; useNO_PROXYfor hosts that must bypass it. - Pyppeteer’s Chromium download: the first run can download a browser (legacy documentation says about 100 MB; the current repository README says roughly 150 MB, depending on revision). Run
pyppeteer-installexplicitly after configuring the network, or use a browser already installed on the machine. - Browser page traffic: Chromium needs its own
--proxy-servercommand-line flag. Pass it through Pyppeteer’slaunch(args=[...]).
Keeping these paths separate explains the most common failure: pip succeeds through a corporate proxy, but page.goto() still connects directly (or fails).
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →Prerequisites and compatibility
- Use Python 3.8 or newer, as stated by the current Pyppeteer continuation README.
- Create an isolated virtual environment so Pyppeteer and its dependencies do not conflict with system packages.
- Obtain a proxy endpoint from your network administrator or provider. Confirm its scheme (HTTP, HTTPS, or SOCKS where supported), host, port, authentication method, and acceptable-use rules.
- Expect maintenance risk: Pyppeteer is an unofficial Python port, and the original project is described as unmaintained. Pin and test versions in production rather than assuming every Chromium revision remains compatible.
Install Pyppeteer and prepare Chromium
- Create and activate a virtual environment.
python3 -m venv .venv . .venv/bin/activateOn Windows PowerShell, activate with
.venvScriptsActivate.ps1. - Upgrade pip and install Pyppeteer.
python3 -m pip install --upgrade pip python3 -m pip install pyppeteerIf the package index is reachable only through a proxy, set the environment before these commands. For example, in a Unix-like shell:
#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.
export HTTPS_PROXY=http://proxy.example:8080 export HTTP_PROXY=http://proxy.example:8080 # Optional hosts that should bypass the proxy: export NO_PROXY=localhost,127.0.0.1,.internal.exampleUse the equivalent environment configuration supported by your platform. Do not place credentials in a command that will remain in shell history.
- Download Chromium before running your application (optional but useful for predictable deployment).
pyppeteer-installIf the download is blocked, set the required proxy environment first. Pyppeteer also documents
PYPPETEER_DOWNLOAD_HOSTfor an approved mirror host andPYPPETEER_CHROMIUM_REVISIONfor selecting a revision. Only use a mirror and revision your organization has approved. - Alternatively, use an installed browser. Find the executable supplied by your base image or IT team and pass its path as
executablePath. Pyppeteer documents this option but warns that arbitrary browser versions are not guaranteed to be compatible.
Launch Chromium through a single proxy
A single URI is the simplest configuration and applies one endpoint broadly:
import asyncio
from pyppeteer import launch
async def main():
browser = await launch(
headless=True,
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 example host and port with your endpoint. The finally block matters: it closes Chromium even when navigation raises an exception. networkidle2 waits until network activity is low, but pages with long polling may never become truly idle; choose a bounded timeout and a more suitable wait condition for those sites.
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.
Use an existing Chrome or Chromium binary
browser = await launch(
headless=True,
executablePath="/usr/bin/chromium",
args=["--proxy-server=http://proxy.example:8080"],
)Adjust the path for your operating system or container image. Test the exact browser revision in CI because Pyppeteer’s protocol expectations may not match every vendor build.
Free tools Windows power users keep installed
One-click scans. No signup required.
Choose proxy routing deliberately
| Configuration | Example | When to use it |
|---|---|---|
| One proxy URI | --proxy-server=http://proxy.example:8080 |
All applicable browser traffic should use one endpoint. |
| Per-scheme mapping | --proxy-server=http=foopy:80;ftp=foopy2:80 |
Different schemes require different endpoints. |
| Direct connection | --proxy-server=direct:// |
A controlled diagnostic or an explicit bypass; do not use it to evade an organizational policy. |
Chromium defines the --proxy-server form as either one URI or semicolon-separated scheme mappings. Keep the value as one argument in the Python list. Do not confuse a proxy URL with a destination URL: the destination remains the argument to page.goto().
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
Authentication, certificates, and secrets
The flag syntax establishes an endpoint, not a provider-neutral credential workflow. Proxy username/password handling differs by provider, enterprise policy, and Chromium version. Check that provider’s documented method before adding credentials. Avoid embedding secrets in source, Docker layers, process listings, or public logs; supply them through a secret manager or runtime environment and follow your provider’s supported authentication flow.
Enterprise proxies may intercept TLS and install a private certificate authority. If Chromium reports certificate errors, ask the administrator for the required trust-chain configuration rather than disabling certificate checks. A setting that suppresses certificate validation can expose page data and should not be a production workaround.
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.
When installation or the browser download is blocked
Package installation fails
Verify that HTTP_PROXY and HTTPS_PROXY are visible in the same shell or service environment running python3 -m pip. Check NO_PROXY for an accidental match that bypasses the required proxy. If your organization uses an internal package index, configure pip according to its administrator’s instructions rather than copying credentials into a command line.
pyppeteer-install cannot fetch Chromium
Run it after setting the download proxy environment. If outbound downloads are prohibited, have an administrator mirror the approved archive and set PYPPETEER_DOWNLOAD_HOST; or provide a compatible local browser with executablePath. A successful package install does not prove that the browser archive is reachable.
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
Page navigation ignores the proxy
Environment variables used by pip do not configure Chromium. Confirm that the launch call contains args=["--proxy-server=SCHEME://HOST:PORT"], that the scheme and port are correct, and that no later launch code replaces the argument list. Test with a simple page and inspect the proxy’s access logs when available.
Diagnostics and common errors
- “No module named pyppeteer”: the application is using a different interpreter. Activate the virtual environment and install with that interpreter’s
python -m pip. - Chromium executable not found: run
pyppeteer-install, or set a validexecutablePath. Check file permissions inside the container. - Timeout during
goto: distinguish DNS, proxy authentication, TLS inspection, and a genuinely slow page. Try a known-small URL, increase the navigation timeout only after identifying the cause, and use an explicit wait strategy instead of an unlimited network-idle wait. - Proxy connection refused: verify DNS resolution from the machine running Chromium, the port, firewall egress rules, and whether the endpoint expects HTTP versus SOCKS.
- HTTP 407 or an authentication prompt: the proxy requires credentials or a different enterprise authentication mechanism. Configure that mechanism as documented by the proxy provider; changing the destination URL will not fix it.
- Blank or incomplete render: wait for a selector or a short, bounded delay after navigation, and check whether the proxy blocks scripts or assets. Avoid treating a screenshot taken before critical content loads as a successful capture.
Operational guidance: reliability, performance, and cost
- Warm the browser: launching Chromium is expensive. Reuse one browser process for multiple pages when isolation requirements allow, while closing each page and periodically recycling the process.
- Bound every wait: set navigation and selector timeouts appropriate to your workload. Retries should be limited and should not repeat non-idempotent actions blindly.
- Separate failures in logs: record whether the failure occurred in pip, the Chromium download, proxy connection, navigation, or rendering. Never log proxy credentials or full authorization headers.
- Control concurrency: many simultaneous pages can exhaust proxy connection limits, file descriptors, memory, or upstream bandwidth. Start conservatively and measure queue time, navigation time, and error rate.
- Plan storage and bandwidth: the first-run Chromium archive can be approximately 100–150 MB depending on documentation generation and revision. Cache the approved browser in a build layer when policy permits.
- Validate in the target network: a laptop test does not prove that a CI runner, serverless function, or container has the same DNS, certificates, proxy routes, or browser dependencies.
Or skip the browser setup
If your goal is a website screenshot rather than browser automation, ScreenshotNeo provides a hosted screenshot API and MCP server. It accepts a URL and returns PNG, JPEG, WebP, or PDF, so there is no Chromium download or proxy wiring in your application:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for options and response details. Before capture, it can accept consent banners and remove more than 60 known consent platforms, newsletter popups, and chat widgets; each step can be disabled. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed as clean shots, and response headers identify the page verdict and billing status. Its MCP server exposes take_screenshot, get_page_info, and capture_pdf for Claude, Cursor, and other MCP clients. The free plan includes 1,000 screenshots per month without a card; paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account to try it.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Decision checklist
- Need DOM interaction, clicks, custom automation, or a private in-process browser? Use Pyppeteer and configure each network path separately.
- Need repeatable screenshots or PDFs without maintaining Chromium, proxy credentials, and browser binaries? Use a hosted capture API.
- Need AI-agent access to capture tools? An MCP server can remove the browser setup from the agent runtime.
Frequently Asked Questions
Does setting HTTPS_PROXY configure Chromium automatically?
No. Those variables commonly affect Python tooling; pass Chromium’s –proxy-server flag through launch(args=[…]).
Can I avoid downloading Pyppeteer’s Chromium?
Yes. Run pyppeteer-install, or provide a compatible installed browser with executablePath. Compatibility with arbitrary browser versions is not guaranteed.
Where should proxy credentials go?
Use the authentication mechanism documented by your proxy provider or enterprise administrator. Keep credentials out of source code, shell history, logs, and process listings.
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.
