Install & Compatibility
Where this runs
tested against v2.0.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
launch
✓ from pyppeteer import launch
$
✓ await page.querySelector('.selector')
✗ await page.$('.selector')
The '$' symbol is not valid for method names in Python. Use `querySelector`, `querySelectorAll`, or `xpath` methods. Shorthands `J()`, `JJ()`, `Jx()` also exist for convenience.
This quickstart launches a headless Chromium browser, opens a new page, navigates to 'https://example.com', prints the page title, takes a screenshot saved as 'example.png', and then closes the browser. It uses Python's `asyncio` for asynchronous execution.
import asyncio
from pyppeteer import launch
import os
async def main():
# Launch the browser in headless mode by default
# Set headless=False to see the browser UI
browser = await launch(headless=True)
page = await browser.newPage()
await page.goto('https://example.com')
print(f"Page title: {await page.title()}")
await page.screenshot({'path': 'example.png'})
await browser.close()
if __name__ == '__main__':
asyncio.run(main())
Debug
Known issues
deprecatedThe Pyppeteer project is officially unmaintained, and the PyPI page explicitly recommends considering `playwright-python` as an alternative for new projects or those requiring active development and broader browser support.fixFor new projects, evaluate `playwright-python` or other actively maintained browser automation libraries. For existing projects, be aware that future updates, bug fixes, or compatibility with newer Chromium versions may be limited.
affects: All versions (starting from 1.0.0 and subsequent releases).
gotchaPyppeteer relies on Python's `asyncio`. Forgetting to `await` asynchronous calls can lead to `Protocol error: Target closed`, `Execution context was destroyed`, non-deterministic behavior, or silent failures, especially during navigation or element interactions.fixEnsure all Pyppeteer API calls that return awaitable objects (e.g., `launch()`, `newPage()`, `goto()`, `click()`, `evaluate()`) are prefixed with `await`. Always run your main async function using `asyncio.run()` or `asyncio.get_event_loop().run_until_complete()`.
affects: All versions.
gotchaUpon first execution, Pyppeteer automatically downloads a compatible Chromium binary (approx. 100-150MB). This can cause delays, consume bandwidth, and may fail in environments without internet access or with strict firewalls. The downloaded Chromium version might become outdated.fixTo pre-emptively download Chromium, run `pyppeteer-install` in your terminal. For controlled environments, consider specifying an `executablePath` to a pre-installed Chrome/Chromium binary or setting the `PYPPETEER_CHROMIUM_REVISION` environment variable. Ensure the specified Chromium version is compatible with your Pyppeteer installation.
affects: All versions.
gotchaPyppeteer's `Page.evaluate()` method expects a JavaScript string, unlike the original Puppeteer which can accept raw JavaScript functions. While Pyppeteer attempts automatic detection, it may fail for expressions, leading to errors.fixIf `evaluate()` raises an error when passing an expression string, explicitly add `force_expr=True` to the call to force Pyppeteer to treat the string as an expression.
affects: All versions.
gotchaThe default navigation timeout for `page.goto()` and other navigation-related methods is 30 seconds. Pages with heavy JavaScript, slow network conditions, or complex rendering can exceed this, resulting in a `Navigation Timeout Exceeded` error.fixIncrease the timeout by passing a `timeout` option to the method, e.g., `await page.goto(url, {'timeout': 60000})` for a 60-second timeout, or set a global default timeout. affects: All versions.
Errors
Common errors & fixes
pyppeteer.errors.BrowserError: No running Chromium browser is found. Please install Chromium manually or run 'pyppeteer-install'.
Pyppeteer could not locate the necessary Chromium executable because it hasn't been downloaded or is not in a path accessible to Pyppeteer.
fixRun the `pyppeteer-install` command in your terminal or specify the exact path to the Chromium executable using the `executablePath` option in `pyppeteer.launch()`.
AttributeError: 'coroutine' object has no attribute 'goto'
An asynchronous Pyppeteer method (e.g., `browser.newPage()`) was called but not awaited, causing subsequent operations to be attempted on the coroutine object itself rather than its returned value (e.g., a `Page` object).
fixEnsure all asynchronous Pyppeteer method calls are prefixed with the `await` keyword, for example: `page = await browser.newPage()`.
pyppeteer.errors.TimeoutError: Navigation Timeout Exceeded: 30000ms
A page navigation or another expected browser action took longer than the default (30 seconds) or specified timeout period to complete.
fixIncrease the timeout value for the specific action (e.g., `await page.goto(url, {'timeout': 60000})`) or globally for the page or browser instance. pyppeteer.errors.NetworkError: Protocol error (Target.closeTarget): Target closed.
The browser tab or the entire browser instance was closed prematurely or unexpectedly while an operation was in progress, disrupting the communication protocol.
fixImplement robust error handling (e.g., `try...except...finally` blocks) to ensure resources are properly managed and closed, and investigate if the browser is crashing due to excessive memory usage or unhandled pop-ups.
Upgrade
Version history
2.0.0latest on PyPI · released Feb 18, 2024
Audit
Dependencies
ChromiumrequiredPyppeteer requires a Chromium browser executable to function. It automatically downloads a compatible version on its first run if not found, or users can manually pre-download it using the 'pyppeteer-install' command. The specific revision can be controlled via the PYPPETEER_CHROMIUM_REVISION environment variable.