Skip to content

How to take a screenshot with Puppeteer

Capture a rendered page in Puppeteer by choosing a viewport, opening the target page, and saving the image with page.screenshot().

OUTPUT FORMATSHTMLJSONMarkdown

This guide explains the sequence, the decisions that affect the result, and a practical checklist for reliable captures.

The three-step capture sequence

A Puppeteer screenshot has three core steps. First, launch a browser and open a new page. Second, define the viewport so the capture area matches the device or layout you want to inspect. Third, navigate to the target URL and call page.screenshot() with a destination path. Keeping this order matters: changing the viewport after navigation can produce a different layout than the one you intended to record, while capturing before the page loads can save an incomplete view.

Choose the viewport deliberately

Treat the viewport as a framing decision, not a cosmetic detail. A 1920 by 1080 setting suits a desktop review, while a narrower width may reveal responsive breakpoints, wrapping text, or hidden navigation. Decide the width and height before loading the page, then keep them consistent across a set of captures so images remain comparable. If you need a full-page view rather than only the visible area, plan that as a separate capture mode and verify the resulting dimensions before using the image for layout checks.

Handle errors and always clean up

Use a try, catch, and finally structure around the capture. Log the error message if screenshot fails, and always close the browser in the finally block. This prevents a failed capture from leaving a browser process running and makes repeated runs cleaner. After a successful run, confirm the file exists at the path you supplied and open it to check that it shows the intended page, viewport, and loading state.

Pre-capture checklist

Before running a capture, work through this checklist: confirm the target URL, set the viewport width and height, wait for the page to reach the state you want to record, choose a clear file path and format, wrap the capture in error handling, close the browser in a finally block, and inspect the saved image. For repeatable visual checks, reuse the same viewport and URL, and name files so each capture can be traced to its page and settings.

Related Puppeteer web scraping questions and tutorial

Related Puppeteer questions cover loading local files, running in Jupyter notebooks, waiting for a page to load, what Puppeteer is, how it compares with Playwright, who owns it, why it is needed, capturing background requests and responses, finding elements by CSS selector or XPath, and saving and loading cookies. For a broader walkthrough, see Learn web scraping with Puppeteer.

Screenshot settings and their effects
DecisionWhat to setWhy it matters
ViewportWidth and height before navigationDefines the visible area and layout breakpoint captured
Target pageURL to open before captureDetermines the content and loading state in the image
Output filePath passed to page.screenshot()Controls where the image is saved and how it is named
CleanupBrowser close in a finally blockEnsures the browser closes after success or failure

Workflow decisions derived from the protected example; viewport values are illustrative, not universal defaults.

Frequently asked questions

What is the basic order for taking a Puppeteer screenshot?

Set the viewport first with page.setViewport(), navigate to the page, then call page.screenshot() with a path for the saved image. Close the browser in a finally block so cleanup happens even if capture fails.

Why set the viewport before capturing?

The viewport dimensions control the visible area that is captured. In the worked example, width 1920 and height 1080 define a desktop-sized capture area before navigation.

How do I choose where the screenshot is saved?

Pass a path option to page.screenshot() to save the image in the current folder. The example saves a JPG file named for the captured homepage.