Pyppeteer

2.0.0 · maintenance · verified Sat Apr 11

Pyppeteer is an unofficial Python port of Puppeteer, a Node.js library for controlling headless Chrome/Chromium. It provides a high-level API for browser automation tasks such as web scraping, automated testing, generating PDFs, and capturing screenshots, leveraging Python's asyncio for asynchronous operations. The current stable version is 2.0.0, though the project is considered to be in a maintenance phase with infrequent updates.

Warnings

deprecated The 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.
Fix: For 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.
gotcha Pyppeteer 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.
Fix: Ensure 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()`.
gotcha Upon 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.
Fix: To 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.
gotcha Pyppeteer'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.
Fix: If `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.
gotcha The 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.
Fix: Increase 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.

Install

pip install pyppeteer Install stable version
pip install -U git+https://github.com/pyppeteer/pyppeteer@dev Install latest development version from GitHub

Imports

launch
```
from pyppeteer import launch
```
$
```
await page.querySelector('.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.

Quickstart

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())

view raw JSON →