What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
Pyppeteer is not documented as Windows-only. It is an unofficial Python port of Puppeteer, and its project instructions describe downloading Chromium when a suitable browser is missing. If your script works on Windows but fails on Linux or macOS, the likely cause is a difference in browser installation, executable path, permissions, architecture, system dependencies, browser version, or runtime environment—not an intentional Windows restriction. Without the exact error and machine details, there is no reliable way to identify which one applies.
This guide walks through a platform-neutral diagnosis, gives a corrected launch pattern, and explains when switching to Playwright Python is worth considering. The project’s current README also describes Pyppeteer as unmaintained, an important maintenance consideration but not evidence that it cannot run outside Windows. Pyppeteer project repository
Why Pyppeteer can work on Windows but fail elsewhere
Pyppeteer code often looks portable while the browser environment beneath it is not. The Python script may be identical on two machines, but each machine can have a different Python environment, downloaded Chromium, filesystem layout, access permissions, CPU architecture, or set of operating-system dependencies. A script copied from Windows can also contain a Windows-only browser path.
Pyppeteer’s current project README says Python 3.8 or newer is required and describes downloading Chromium on first use if no suitable binary is available. The API reference documents browser-data directories separately for Windows, macOS, and Linux. Those details are incompatible with the idea that the package is designed only for Windows. Project README · API Reference, version 0.0.25
#1 Best Overall
Common causes to check first
- Different Python environments: Pyppeteer may be installed for one interpreter but the script runs under another virtual environment, service account, or system Python.
- Missing or misplaced Chromium: the browser download may not have run, may be incomplete, or may be stored in a directory different from the one you checked.
- Wrong executable path: a hard-coded Windows path will not identify a Linux or macOS browser binary.
- Permissions or runtime differences: a browser executable that works for your desktop user may not be readable or launchable for a service, container, or CI account.
- Browser compatibility: a locally installed Chrome or Chromium is not guaranteed to match the version Pyppeteer expects.
- Platform-specific launch failure: a browser may be found but still fail to start because of architecture, system dependencies, or environment configuration.
The precise failure cannot be diagnosed from “works only on Windows” alone. Keep the complete exception and compare the operating system, architecture, Python and Pyppeteer versions, browser version, and execution context on both machines.
Fix it in a reliable order
Start with the least invasive checks. Avoid changing browser security settings or swapping browser versions before confirming which interpreter and browser the failing process is actually using.
- Identify the interpreter running the script. Activate the same virtual environment, container, or service environment used in production. Install Pyppeteer there, not merely in a different terminal’s default Python.
- Install Pyppeteer’s Chromium in that environment. The project documents
pyppeteer-installas a way to download Chromium before running the script. Run it using the environment that will launch the program. Pyppeteer installation instructions - Check the browser-data location. Confirm the browser files exist and are readable by the account that runs your code. If the default location is not where you expect, inspect
PYPPETEER_HOME; on Linux, also checkXDG_DATA_HOME. - Try the bundled browser before a system browser. Omit
executablePathand allow Pyppeteer to use its downloaded Chromium. This avoids assuming that a system browser version is compatible. - If necessary, test a local browser explicitly. Use
executablePathwith the actual Chrome or Chromium executable path on that machine. Do not copy a Windows path, package name, or another user’s home-directory path as if it were universal. - Capture the details of any remaining launch error. Record OS and architecture, Python and Pyppeteer versions, browser version, exact exception, the account executing the script, and whether it runs in a container or CI runner.
Install Chromium and understand its location
On a fresh setup, the project’s documented standalone installation command is:
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Scan for outdated or missing drivers - takes under a minute3Repair Windows errors before they cause bigger problemspyppeteer-installThis downloads Chromium before your application starts. The repository gives an approximate download size of 150 MB; it is the project’s stated approximation, not an independently measured size or a guaranteed download size for every environment. Plan for the download and browser files to be available to the same user and runtime that executes the script. Pyppeteer project repository
Rank #2
The API reference lists these default browser-data locations:
| Operating system | Documented default location |
|---|---|
| Windows | C:Users<username>AppDataLocalpyppeteer |
| macOS | /Users/<username>/Library/Application Support/pyppeteer |
| Linux | /home/<username>/.local/share/pyppeteer, or $XDG_DATA_HOME/pyppeteer |
PYPPETEER_HOME can override the location. These are defaults, not promises that a particular process is using them: environment variables, the active user account, or a customized runtime can change where files are stored. Pyppeteer API Reference
Use a portable launch pattern
Keep browser startup and page work inside an async function, and close the browser in a finally block so an exception does not leave a child browser process behind. The following pattern supports either Pyppeteer’s downloaded Chromium or a deliberately selected local executable:
import asyncio
from pyppeteer import launch
async def main():
browser = await launch(
# Remove this line to use Pyppeteer's downloaded Chromium.
executablePath="/path/to/chrome-or-chromium",
headless=True,
)
try:
page = await browser.newPage()
await page.goto("https://example.com")
print(await page.title())
finally:
await browser.close()
asyncio.run(main())/path/to/chrome-or-chromium is explanatory, not a real path. Replace it with the actual executable path on the target machine, or remove the executablePath argument to use the downloaded browser. The API documents this launch option but warns that Pyppeteer works best with its bundled Chromium and does not guarantee compatibility with another browser version. Treat a system Chrome path as a diagnostic choice, not a guaranteed fix. Launch options and compatibility note
What to compare when the same code behaves differently
- Interpreter and package: verify the failing program imports Pyppeteer from the intended Python environment.
- Browser files: verify that the expected Chromium download completed and that the process user can read and launch it.
- Path: use the target machine’s real executable path only when intentionally testing a local browser.
- Version: note whether the run uses Pyppeteer’s bundled Chromium or an independently installed browser.
- Execution context: compare an interactive shell with the actual service, container, or CI invocation; they may use different environment variables and permissions.
How to investigate errors without guessing
Use the exception text to decide which branch to follow. An executable-not-found error points first to installation or path configuration; a launch failure after the browser is found calls for environment, permissions, dependency, architecture, and version checks. A page that launches but does not load correctly is a different problem from a browser process that never starts.
Executable not found or browser download missing
Run pyppeteer-install in the environment used by the script, then check the documented data directory and overrides. If you configured executablePath, verify that it names a real executable on the target system and is accessible to the process user. Remove the override to test the managed Chromium download.
Browser exists but will not launch
Confirm the file is readable and executable for the launching account, then compare OS architecture and execution context with the working machine. Capture the full exception rather than replacing it with a generic “Pyppeteer failed” message. The sources establish that platform and version differences matter, but do not establish a universal dependency fix for an unspecified machine.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →System Chrome behaves differently from bundled Chromium
That difference may be a browser-version compatibility issue. Pyppeteer’s API reference explicitly says that the bundled Chromium is the best-supported choice and that compatibility with another version is not guaranteed. Test the managed browser first; if you need the system browser, record its exact version and verify the behavior in your own target environment.
One Fedora report is not a general platform diagnosis
A Pyppeteer issue reports a launch hang on Fedora 37 with Python 3.11 and Chrome 115.0.5790.3. It was opened on June 2, 2023, and describes one user’s setup; it does not prove that current Fedora releases, Linux generally, or Pyppeteer universally have the same problem or remedy. Compare your own versions and error before applying advice from that report. Pyppeteer issue #441
Do not make disabling the browser sandbox the default fix
A comment in that issue suggests disabling sandboxing, but the primary API documentation does not present that as a cross-platform remedy. Browser sandbox settings affect security. Do not add a no-sandbox option as a routine workaround; only investigate such a change in a narrowly defined environment after assessing its security implications.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Should you stay on Pyppeteer or move to Playwright?
The current Pyppeteer repository describes the project as unmaintained and recommends considering Playwright Python. That is a maintenance signal, not proof that an existing Pyppeteer script cannot be made to run. If you rely on Pyppeteer-specific behavior, reproduce and diagnose the current failure before deciding to migrate. Pyppeteer project repository
Free tools Windows power users keep installed
One-click scans. No signup required.
| Decision factor | Pyppeteer | Playwright Python |
|---|---|---|
| Maintenance signal | The current repository says the project is unmaintained. | Official Python documentation provides installation, browser management, and usage guidance. |
| Browser management | Downloads Chromium when needed, offers pyppeteer-install, and permits an executablePath override. |
Installs browser binaries separately through its browser installation commands and documents browser management. |
| API choices | Uses Pyppeteer’s async API. | Documents both synchronous and asynchronous APIs. |
| Migration effort | Existing code uses Pyppeteer method names and behavior. | Expect to adapt code and test it; source compatibility is not promised. |
Playwright’s documented setup separates installing the Python package from installing browser binaries. Its library guide covers synchronous and asynchronous use, while its browser guide explains browser installation and cache management. Review both before estimating a migration, especially if scripts run in a controlled CI or deployment environment. Playwright Python: Getting started · Playwright Python: Browsers
Or skip the browser setup
If your task is simply to capture a website rather than automate a browser session, ScreenshotNeo provides a screenshot API. It accepts one GET request with a URL and returns a PNG, JPEG, WebP, or PDF. Its clean-shot options accept consent banners and remove more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and the response identifies the page verdict and billing status in headers. An MCP server provides take_screenshot, get_page_info, and capture_pdf tools for AI agents.
For example, save a WebP screenshot of a page with cURL:
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 setup and options. ScreenshotNeo also supports full-page capture, CSS-selector element capture, dark mode, device presets and custom viewports, retina scale, PDF settings, HTML/CSS capture, custom CSS and JavaScript, click-before-capture, hiding selectors, wait conditions, request blocking, custom headers and cookies, user agents, authorization, timezone and geolocation, transparent backgrounds, resizing, configurable cache TTL, signed image links, asynchronous jobs with signed webhooks, bulk capture of up to 100 URLs per call, usage API, and an OpenAPI specification. Parameters used by other screenshot APIs also work to make switching easier.
There is a free plan with 1,000 screenshots per month and no card required; paid plans start at $5 for 3,000 screenshots. ScreenshotNeo is made by Yorker Media. Sign up free for 1,000 screenshots a month with no card.
FAQ
Is Pyppeteer officially maintained by the Google Puppeteer team?
No. Pyppeteer is an unofficial Python port of Puppeteer; consult its project repository for its current maintenance status.
Can I use Pyppeteer with Python 3.7?
The current project repository states Python 3.8 or newer as a requirement. Check the repository’s current instructions if your deployment must use an older interpreter.
Does fixing the browser path guarantee that a page will load?
No. A correct executable path can address browser discovery, but page navigation can still fail for unrelated network, website, or runtime reasons. Diagnose the browser launch and page load as separate stages.
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.
