To save a webpage screenshot with Pyppeteer, launch Chromium, open a page, navigate to a URL, call page.screenshot(), then close the browser. Pyppeteer is an unofficial Python port of Puppeteer; its project README currently describes it as unmaintained and suggests Playwright Python instead. This walkthrough is for developers who specifically need Pyppeteer or are maintaining an existing script—not a default recommendation for a new project. The examples follow the project README’s API; verify them in your target Python and Chromium environment.
Install Pyppeteer and prepare Chromium
The Pyppeteer repository README documents Python 3.8 or later as its baseline requirement. Because the project is unmaintained, that documented baseline does not guarantee compatibility with every current Python or Chromium setup. See the Pyppeteer repository README for project status and installation details.
-
Create and activate a virtual environment using your usual Python workflow.
-
Install the package:
python -m pip install pyppeteer.Recommended: Crashes or Glitches? A Free Driver Scan Usually Finds the Culprit →Recommended: PC Feels Slow? A Free Scan Shows What's Dragging Windows Down →Recommended: Update Every Outdated Driver on Your PC in One Scan - Free →Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy. -
On first use, Pyppeteer may download Chromium if it cannot find a local browser. To provision it before running the script, use
pyppeteer-install.
The repository describes the browser download size only approximately; it can change, so allow for network access and sufficient disk space rather than treating a particular size as guaranteed.
Save a full-page screenshot with Pyppeteer
Save the following as screenshot.py. It uses the repository’s documented event-loop example, sets a navigation timeout, waits for the page’s load event, writes a PNG, and closes the browser even if navigation or capture raises an error.
import asyncio
from pyppeteer import launch
async def main():
browser = await launch()
try:
page = await browser.newPage()
page.setDefaultNavigationTimeout(60000)
await page.goto("https://example.com", {"waitUntil": "load"})
await page.screenshot({"path": "example.png", "fullPage": True})
finally:
await browser.close()
asyncio.get_event_loop().run_until_complete(main())Run it with python screenshot.py. The output file example.png is written to the current working directory. The launch → page → navigation → screenshot → close sequence follows the Pyppeteer repository’s example; the event-loop runner shown there is an example, not the only valid runner in every Python context.
Choose the page-readiness condition deliberately
The example waits for load, which means the page’s load event has fired; it does not prove that every dynamically rendered component or image is ready. If the site renders content later, wait for a meaningful selector before capturing:
await page.goto("https://example.com", {"waitUntil": "domcontentloaded"})
await page.waitForSelector("main article")
await page.screenshot({"path": "article.png", "fullPage": True})Use a selector that actually appears when the content you need is ready. For sites that continue updating after the selector appears, add a deliberate delay only when necessary, or wait on a more specific condition in your page.
Capture one element instead of the whole page
Pyppeteer exposes element-level screenshots through an element handle. Navigate, find the target, and capture that element:
element = await page.querySelector(".report-card")
if element is None:
raise RuntimeError("Could not find .report-card")
await element.screenshot({"path": "report-card.png"})The selector must match an element in the loaded page. This is the Python form of the element screenshot workflow; the official Puppeteer screenshot guide documents the corresponding screenshot concept in JavaScript. Do not assume that JavaScript snippets from Puppeteer can be pasted unchanged into Pyppeteer.
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 problemsCommon failures and practical fixes
-
Chromium download or launch fails: check network access and permissions for the browser download location, then try
pyppeteer-installbefore rerunning the script. -
The script times out during navigation: confirm the URL is reachable from the machine running the script and increase the navigation timeout if the site is legitimately slow. Do not use an unlimited wait as a substitute for diagnosing a stalled page.
-
The screenshot is blank or missing late content: wait for the relevant selector or a page-specific readiness condition before calling
screenshot; the load event alone may not cover client-side rendering. -
An element screenshot fails: verify that the selector matches an element after navigation. Handle a missing element explicitly instead of assuming it exists.
Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy. -
Browser compatibility is uncertain: Pyppeteer’s maintenance status makes current browser compatibility uncertain. Puppeteer’s current Chrome for Testing support information is for Puppeteer, not a Pyppeteer compatibility matrix. Do not infer that a current Chrome release is supported by Pyppeteer without validating your particular combination. See Puppeteer’s supported browsers documentation.
When to keep Pyppeteer—and when to consider Playwright
Keeping Pyppeteer can be practical when an existing workflow depends on its API and runs reliably in a controlled environment. For a new project, or if you need a maintained project to evaluate, Pyppeteer itself names Playwright Python as an alternative. Playwright’s official Python documentation shows browser launch and screenshot workflows for Chromium, Firefox, and WebKit, but this does not establish a feature-by-feature comparison or guarantee a better outcome in every deployment. Review the Playwright Python screenshot documentation and test the browser, provisioning, API changes, and deployment constraints that matter to your application.
Or skip the browser setup
If you need a screenshot without provisioning and operating a browser, ScreenshotNeo provides a website screenshot API and MCP server. A single GET request returns an image or PDF. Its clean-shot flow accepts cookie or consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, with the outcome reported in response headers. Its MCP server provides screenshot and page-info tools for AI-agent clients.
For example, save a screenshot with cURL:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com -o shot.webpSee the ScreenshotNeo API documentation for request options and setup. The Free plan includes 1,000 shots per month with no card; paid plans start at $5 for 3,000 shots. Sign up for 1,000 free screenshots a month, with no card required.
Frequently Asked Questions
Can I run the repository’s asyncio example inside an already-running event loop?
The repository’s run_until_complete example is intended as a script runner; an already-running event loop needs a runner appropriate to that environment.
Does Pyppeteer support every current Chrome release?
The cited documentation does not establish a current Chrome compatibility matrix for Pyppeteer. Puppeteer’s browser support information applies to Puppeteer, not automatically to Pyppeteer.
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.
