{"id":3232,"library":"pyppeteer","title":"Pyppeteer","description":"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.","status":"maintenance","version":"2.0.0","language":"en","source_language":"en","source_url":"https://github.com/pyppeteer/pyppeteer","tags":["web scraping","browser automation","headless browser","chromium","puppeteer","asyncio"],"install":[{"cmd":"pip install pyppeteer","lang":"bash","label":"Install stable version"},{"cmd":"pip install -U git+https://github.com/pyppeteer/pyppeteer@dev","lang":"bash","label":"Install latest development version from GitHub"}],"dependencies":[{"reason":"Pyppeteer 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.","package":"Chromium","optional":false}],"imports":[{"symbol":"launch","correct":"from pyppeteer import launch"},{"note":"The '$' symbol is not valid for method names in Python. Use `querySelector`, `querySelectorAll`, or `xpath` methods. Shorthands `J()`, `JJ()`, `Jx()` also exist for convenience.","wrong":"await page.$('.selector')","symbol":"$","correct":"await page.querySelector('.selector')"}],"quickstart":{"code":"import asyncio\nfrom pyppeteer import launch\nimport os\n\nasync def main():\n    # Launch the browser in headless mode by default\n    # Set headless=False to see the browser UI\n    browser = await launch(headless=True)\n    page = await browser.newPage()\n    await page.goto('https://example.com')\n    print(f\"Page title: {await page.title()}\")\n    await page.screenshot({'path': 'example.png'})\n    await browser.close()\n\nif __name__ == '__main__':\n    asyncio.run(main())\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"deprecated","affected_versions":"All versions (starting from 1.0.0 and subsequent releases)."},{"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()`.","message":"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.","severity":"gotcha","affected_versions":"All versions."},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions."},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions."},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions."}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}