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 an unofficial Python port of Puppeteer for automating Chrome and Chromium. The most important thing to know before adopting it is that the project’s README calls it unmaintained and recommends Playwright Python instead. Pyppeteer can still matter when you are maintaining an existing script or planning a migration; for a new browser-automation project, weigh that maintenance status against the work required to move to a supported alternative.
What Pyppeteer is—and what its maintenance status means
Pyppeteer lets Python code control a headless Chrome or Chromium browser. It aims to reproduce Puppeteer’s API, but it is an unofficial port rather than the official Puppeteer library. Puppeteer’s own documentation describes Puppeteer as a JavaScript library for controlling Chrome or Firefox, so Pyppeteer is not simply Puppeteer with a different language binding. Pyppeteer’s repository README explicitly says the project is unmaintained and asks readers to consider Playwright Python.
The PyPI page for version 2.0.0 repeats the unmaintained notice; it does not establish a precise last-release date that should be presented as current. PyPI’s Pyppeteer 2.0.0 page is useful for package information, but a version number alone is not evidence of ongoing compatibility work.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallThat status does not make existing Pyppeteer code unusable. It does change the adoption decision: your team should be prepared to investigate browser or environment incompatibilities itself, pin the dependencies and browser setup it relies on, and assess whether migration is less costly than continuing to maintain the code.
#1 Best Overall
Install Pyppeteer and prepare Chromium
The current project README specifies Python 3.8 or later and installs Pyppeteer with pip. When no suitable Chrome binary is available, the first run may download Chromium. The project also provides pyppeteer-install so you can trigger that setup explicitly instead of discovering the download during a production run. Its README estimates the download at about 150 MB, but the actual size is version- and platform-dependent. Check the README’s current setup instructions for the environment you use.
- Use a supported Python version. The current repository guidance is Python 3.8 or later.
- Install the package:
python -m pip install pyppeteer. - Optionally prepare the browser in advance: run
pyppeteer-installin the environment that will execute the script. - Run a small capture or automation task before deployment. Confirm that the browser binary can launch in the same operating system, container, and permission context as your application.
Browser installation is part of the operational setup, not just a Python dependency. In a container or restricted runtime, check that the downloaded or configured browser binary is present and can launch. Avoid assuming that a local development machine’s browser setup will automatically exist on a deployment host.
A minimal Pyppeteer script
This asynchronous example launches a browser, opens a page, navigates to a URL, saves a screenshot, and closes the browser even if navigation or capture raises an error. It illustrates the basic workflow; it is not a guarantee that every site will load or render identically in every environment.
import asyncio
from pyppeteer import launch
async def main():
browser = await launch()
try:
page = await browser.newPage()
await page.goto("https://example.com", {"waitUntil": "networkidle2"})
await page.screenshot({"path": "example.png", "fullPage": True})
finally:
await browser.close()
asyncio.run(main())For a real application, choose a navigation wait condition that fits the target. A page with persistent network activity may never reach a network-idle condition; a simpler page-load event or waiting for a specific selector can be more appropriate. If your code needs a particular viewport, set it before navigation or capture. Treat timeouts, redirects, cookie dialogs, and delayed content as expected cases to handle rather than assuming one navigation call covers every site.
Where Pyppeteer differs from Puppeteer
Pyppeteer follows Puppeteer’s general model—launch a browser, create pages, navigate, inspect or interact with content—but the project warns that language differences prevent exact API equivalence. Code copied from JavaScript Puppeteer examples should be checked against Pyppeteer’s own API reference and exercised in the target environment. Pyppeteer documentation provides the project’s reference material.
Selectors use Python-compatible method names
JavaScript’s $ and $$ method names are not available as Python identifiers. Pyppeteer documents methods such as querySelector, querySelectorAll, and xpath, along with shorthand methods. When porting a snippet, translate the selector call instead of assuming the JavaScript spelling will work unchanged.
JavaScript evaluation takes source text
Pyppeteer’s evaluate accepts JavaScript source as a string. The README notes that if an expression is interpreted as a function when that is not what you intended, try force_expr=True. This behavior is a practical porting edge: an expression that looks obvious in a JavaScript example may need explicit handling in Python.
Free tools Windows power users keep installed
One-click scans. No signup required.
Test the operations your application actually uses
API resemblance is not a drop-in compatibility promise. Pay particular attention to selectors, evaluation, event handling, waits, and browser launch options in the parts of your code that matter. Pin the Python package and browser environment used by the application, and keep a small regression test that verifies the page interaction or output your workflow depends on.
Should you keep Pyppeteer or move to Playwright Python?
The Pyppeteer maintainers themselves point users toward Playwright Python. The right choice depends on whether you are preserving a working legacy script or starting a system whose browser support you will need to maintain.
| Decision factor | Pyppeteer | Playwright Python |
|---|---|---|
| Maintenance signal | The repository README says it is unmaintained. Project README | Review the current project and release information when adopting it; the Pyppeteer README recommends it as the alternative. Playwright Python documentation |
| Python interface | Python port with documented differences from Puppeteer, including selector naming and evaluation behavior. | Official documentation describes both synchronous and asynchronous Python APIs. Playwright Python library documentation |
| Browser engines | Presented as a Chrome/Chromium automation port. | Official Python documentation lists Chromium, Firefox, and WebKit. Playwright Python library documentation |
| Browser binary management | May download Chromium on first use; the repository documents a separate install command. | Each Playwright version expects specific browser binaries; updates may require running the browser installation command again. Playwright browser documentation |
| Migration cost | Lowest immediate change for code already built around Pyppeteer, but future compatibility work remains your responsibility. | Requires porting and validating the operations your application uses; the effort depends on its actual API usage and deployment setup. |
For a new project
Start by evaluating Playwright Python rather than choosing Pyppeteer by default. Its documented sync and async interfaces give you a choice of programming model, and its official documentation lists three browser engines. Include browser-binary installation in your upgrade process: Playwright ties expected browser binaries to its version, and an update can require reinstalling them.
For an existing Pyppeteer project
Do not migrate blindly just because the README says the project is unmaintained. First inventory how the application uses Pyppeteer, identify its browser and operating-system constraints, and estimate the effort to port selectors, evaluations, waits, and interactions. If the script is stable and isolated, a pinned environment may be a reasonable short-term maintenance choice; if it needs ongoing browser compatibility or broader engine coverage, test a Playwright migration against the real workflow.
When a screenshot service is a better fit
If the requirement is to obtain screenshots or PDFs rather than to control an entire browser session, a screenshot API can avoid managing a local browser binary and launch process. ScreenshotNeo is a website screenshot API and MCP server for developers. It accepts a URL in a GET request and returns an image or PDF; its clean-shot flow accepts cookie or consent banners like a visitor and removes 60+ known consent platforms, newsletter popups, and chat widgets before capture. Each of those cleanup steps can be turned off. See ScreenshotNeo for the service overview.
It is not a general replacement for arbitrary browser automation: use Pyppeteer or Playwright when your program must carry out a larger interactive workflow, and consider a screenshot service when the output itself is the main job. ScreenshotNeo reports page verdict and billing status in response headers; bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing according to its stated billing rules.
Or skip the browser setup
For a straightforward website capture, ScreenshotNeo’s API uses one GET request. Create an API key, substitute it for YOUR_API_KEY, and use the target URL you want to capture. The following cURL command saves the returned image as shot.webp. See the ScreenshotNeo API documentation for request options and response details.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpCookie banners, popups, and chat widgets are removed before the shot; bot checks, blank pages, and failed loads are never billed. An MCP server lets AI agents use take_screenshot, get_page_info, and capture_pdf. The Free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 shots. Sign up for ScreenshotNeo’s free plan.
Troubleshooting Pyppeteer
Chromium download or launch fails
- Symptom: the first run stalls or errors while preparing the browser. Fix: run
pyppeteer-installexplicitly in the deployment environment, then confirm that the process can access the installed binary. - Symptom: a binary exists but will not start. Fix: check operating-system dependencies, filesystem permissions, and container restrictions. A browser that launches on a developer’s machine may not launch in a minimal container.
- Symptom: deployment unexpectedly downloads a large browser. Fix: perform installation during image or environment preparation, and account for the repository’s version- and platform-sensitive download estimate rather than relying on first-use setup.
Navigation times out or never becomes idle
- Cause: the page continues making network requests, or the chosen wait condition does not match the page’s behavior.
- Fix: use a wait condition appropriate to the site, increase the timeout only when the workflow warrants it, or wait for a specific element that signals the content you need is ready.
A copied Puppeteer method or expression behaves differently
- Cause: Pyppeteer is similar to Puppeteer but not identical; Python cannot use the JavaScript dollar-sign selector method names, and evaluation interprets source according to Pyppeteer’s rules.
- Fix: use the documented Python selector methods, check the Pyppeteer reference, and try
force_expr=Truefor an expression that is being treated as a function. Add a focused test for the converted operation.
Playwright launches but cannot find its browser
- Cause: the installed Playwright version expects browser binaries that are not installed or do not match that version.
- Fix: follow the browser installation instructions for the version in your environment, and repeat browser installation when an upgrade requires it. Playwright’s browser guide explains the version relationship.
Practical reliability and cost considerations
For self-hosted automation, budget for browser download and storage, process startup, memory, and the time needed to diagnose site-specific behavior. The available project guidance gives a version- and platform-dependent download estimate, not a reliable universal runtime or resource benchmark. Measure your actual pages and concurrency in the environment where the job will run.
With an unmaintained dependency, upgrade confidence is a project risk rather than a feature to assume. Keep dependencies controlled, exercise the critical path after changing Python, operating systems, or browser binaries, and decide in advance who will handle compatibility failures. A migration comparison should include not only the code edits but also browser installation and deployment changes.
For screenshot-only workloads, an API changes the cost model from running and maintaining browser infrastructure to paying under the service’s usage plan. ScreenshotNeo lists Free at 1,000 shots per month with no card, Starter at $5 for 3,000, Growth at $15 for 15,000, Pro at $39 for 60,000, Scale at $99 for 250,000, and Business at $249 for 1,000,000; yearly billing gives two months free, and every feature is on every plan. Choose based on your expected volume and whether you need browser interaction beyond producing a capture.
Frequently Asked Questions
Is Pyppeteer the official Python version of Puppeteer?
No. It is an unofficial Python port that aims to reproduce Puppeteer’s API.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Does Pyppeteer support Firefox or WebKit?
The project presents Pyppeteer as a Chrome/Chromium automation port. Playwright Python’s official documentation lists Chromium, Firefox, and WebKit.
Can I use Pyppeteer for an existing project?
Yes, but account for the repository’s unmaintained status and validate the browser and API behavior your project relies on.
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.
