How to Take Screenshots with pyppeteer in Python

Important Note: pyppeteer is no longer actively maintained. The last major update was in 2020. For new projects, I strongly recommend using Playwright instead. This guide is for those maintaining legacy code.

pyppeteer is a Python port of Puppeteer, the Node.js browser automation library. While it was groundbreaking when released, it hasn’t kept up with browser changes.

Installation

1
pip install pyppeteer

On first run, pyppeteer downloads Chromium automatically.

Basic Screenshot

1
import asyncio
2
from pyppeteer import launch
3

4
async def take_screenshot():
5
    browser = await launch()
6
    page = await browser.newPage()
7
    await page.goto('https://example.com')
8
    await page.screenshot({'path': 'screenshot.png'})
9
    await browser.close()
10

11
asyncio.get_event_loop().run_until_complete(take_screenshot())

Full Page Screenshots

1
import asyncio
2
from pyppeteer import launch
3

4
async def full_page_screenshot():
5
    browser = await launch()
6
    page = await browser.newPage()
7
    await page.goto('https://example.com')
8
    await page.screenshot({
9
        'path': 'fullpage.png',
10
        'fullPage': True
11
    })
12
    await browser.close()
13

14
asyncio.get_event_loop().run_until_complete(full_page_screenshot())

Viewport Settings

1
async def screenshot_with_viewport():
2
    browser = await launch()
3
    page = await browser.newPage()
4

5
    # Set viewport
6
    await page.setViewport({
7
        'width': 1920,
8
        'height': 1080
9
    })
10

11
    await page.goto('https://example.com')
12
    await page.screenshot({'path': 'screenshot.png'})
13
    await browser.close()

Element Screenshots

1
async def element_screenshot():
2
    browser = await launch()
3
    page = await browser.newPage()
4
    await page.goto('https://example.com')
5

6
    element = await page.querySelector('.hero-section')
7
    await element.screenshot({'path': 'element.png'})
8

9
    await browser.close()

Waiting for Content

1
async def screenshot_with_wait():
2
    browser = await launch()
3
    page = await browser.newPage()
4
    await page.goto('https://example.com')
5

6
    # Wait for selector
7
    await page.waitForSelector('.main-content')
8

9
    # Or wait for navigation
10
    await page.waitForNavigation()
11

12
    await page.screenshot({'path': 'screenshot.png'})
13
    await browser.close()

Headless Mode

1
async def headless_screenshot():
2
    browser = await launch(headless=True)  # Default is True
3
    page = await browser.newPage()
4
    await page.goto('https://example.com')
5
    await page.screenshot({'path': 'screenshot.png'})
6
    await browser.close()

PDF Generation

One advantage pyppeteer shares with Playwright:

1
async def generate_pdf():
2
    browser = await launch()
3
    page = await browser.newPage()
4
    await page.goto('https://example.com')
5
    await page.pdf({
6
        'path': 'page.pdf',
7
        'format': 'A4'
8
    })
9
    await browser.close()

Why Migrate to Playwright?

Feature	pyppeteer	Playwright
Maintained	No (since 2020)	Yes (actively)
Browser support	Chromium only	Chrome, Firefox, Safari
Sync API	No	Yes
Auto-wait	Basic	Advanced
Documentation	Outdated	Excellent
Community	Small	Large

Migration Guide

Most pyppeteer code translates to Playwright with minor changes:

pyppeteer

1
import asyncio
2
from pyppeteer import launch
3

4
async def main():
5
    browser = await launch()
6
    page = await browser.newPage()
7
    await page.goto('https://example.com')
8
    await page.screenshot({'path': 'screenshot.png', 'fullPage': True})
9
    await browser.close()
10

11
asyncio.get_event_loop().run_until_complete(main())

Playwright

1
import asyncio
2
from playwright.async_api import async_playwright
3

4
async def main():
5
    async with async_playwright() as p:
6
        browser = await p.chromium.launch()
7
        page = await browser.new_page()
8
        await page.goto('https://example.com')
9
        await page.screenshot(path='screenshot.png', full_page=True)
10
        await browser.close()
11

12
asyncio.run(main())

Key differences:

launch() → p.chromium.launch()
newPage() → new_page()
{'path': ...} → path=... (keyword args)
fullPage → full_page
asyncio.get_event_loop().run_until_complete() → asyncio.run()

Common Issues with pyppeteer

Chromium Version Mismatch

pyppeteer downloads an old Chromium version that may not work with modern websites:

1
# Workaround: specify executable path
2
browser = await launch(executablePath='/path/to/chrome')

Connection Errors

1
# Increase timeout
2
browser = await launch(timeout=60000)

Memory Leaks

Long-running pyppeteer processes often leak memory. Restart the browser periodically:

1
# Close and reopen browser every N screenshots
2
if screenshot_count % 100 == 0:
3
    await browser.close()
4
    browser = await launch()

Summary

pyppeteer works for simple use cases but has significant limitations:

Not actively maintained
Uses outdated Chromium
Limited browser support
Basic async patterns

Recommendation: Migrate to Playwright for better features, active maintenance, and modern browser support.

Frequently Asked Questions

If you read the article, but still have questions. Please, check the most frequently asked. And if you still have questions, feel free reach out at support@screenshotone.com.

Is pyppeteer still maintained?

No, pyppeteer is no longer actively maintained. The last significant update was in 2020. For new projects, use Playwright instead, which is actively developed and has better features.

What is the difference between pyppeteer and Playwright?

Both are browser automation libraries, but Playwright is actively maintained, supports multiple browsers natively, has better async support, and includes more features. pyppeteer only supports Chromium and is outdated.

How to migrate from pyppeteer to Playwright?

The APIs are similar. Replace 'from pyppeteer import launch' with 'from playwright.async_api import async_playwright', and adjust method names slightly. Most code translates directly.

How to Take Screenshots with pyppeteer in Python

Written by

Published on

Tags