Set Puppeteer’s screenshot resolution with three separate controls: page.setViewport() defines the layout viewport in CSS pixels, deviceScaleFactor sets pixel density, and screenshot options such as fullPage or clip define how much of the page is captured. For a 1280×720 viewport rendered at 2× density, use await page.setViewport({ width: 1280, height: 720, deviceScaleFactor: 2 }) before navigation. A normal viewport shot is then nominally 2560×1440 device pixels, although the final dimensions change when you capture the full page or a clipped region.
What “resolution” means in Puppeteer
Puppeteer does not have one setting called resolution. A screenshot’s result is determined by independent settings:
- Viewport size: the page’s CSS layout width and height.
- Device scale factor (DSF): the number of device pixels represented by each CSS pixel. Puppeteer documents a default of
1. - Captured area: the viewport, the entire document, or a rectangle selected with
clip. - Encoding: PNG, JPEG, or WebP and, for lossy formats, an optional quality value.
CSS dimensions and output-image pixels are therefore different. For a viewport-only capture, approximate raster width is width × deviceScaleFactor and height is height × deviceScaleFactor. A full-page image can be much taller, while a clip can be smaller than the viewport.
The examples below follow the current Puppeteer API documentation (the documentation pages identify version 25.12.0). Check the API that matches the Puppeteer version installed in your project before relying on version-specific behavior.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
#1 Best Overall
Set viewport dimensions and pixel density
Basic 1280×720 screenshot at 2×
const puppeteer = require('puppeteer');
(async () => {
const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.setViewport({
width: 1280,
height: 720,
deviceScaleFactor: 2,
});
await page.goto('https://example.com', { waitUntil: 'networkidle0' });
await page.screenshot({ path: 'shot.png' });
await browser.close();
})();width and height are CSS pixels. With the settings above, the viewport capture is nominally 2560×1440 device pixels. PNG is the default screenshot type when no other type is selected.
Choose a density
Use deviceScaleFactor: 1 for a standard-density render, 2 for a retina-like capture, or another positive value when your workflow needs it. Puppeteer documents 0 as resetting the factor to the system default. Increasing DSF increases raster dimensions and usually memory and file size; it does not change CSS layout breakpoints.
Set the viewport before navigation
Set the viewport as early as possible, normally immediately after creating the page and before goto. Puppeteer notes that changing mobile emulation or touch settings can cause a reload, so applying those values before navigation avoids an unnecessary second load and prevents capturing an intermediate layout.
Capture only the viewport
Omit fullPage and clip to capture the visible viewport:
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →await page.setViewport({ width: 1440, height: 900, deviceScaleFactor: 1 });
await page.goto('https://example.com', { waitUntil: 'networkidle0' });
await page.screenshot({ path: 'viewport.png', type: 'png' });The output corresponds to the viewport’s CSS dimensions multiplied by DSF. Content below the fold is not included.
Rank #2
- HTML CSS Design and Build Web Sites
- Comes with secure packaging
- It can be a gift option
Take a full-page screenshot
Full document
await page.screenshot({
path: 'full-page.png',
fullPage: true,
});fullPage: true captures the complete page rather than only the viewport. The width is based on the page layout and viewport settings; the height depends on document content, so it cannot be predicted from the viewport height alone. Very long pages may require more memory and produce large files.
Lazy-loaded content
A full-page flag does not guarantee that an application has finished loading every image or component. Wait for a reliable selector, an application-ready signal, or an appropriate network-idle state before capturing. If the site loads content only after scrolling, trigger that behavior in the page first and then take the full-page shot.
Capture a precise region with clip
Use a clip rectangle when the desired output is a known region. Coordinates and dimensions are CSS pixels; DSF determines the resulting device-pixel size.
Free tools Windows power users keep installed
One-click scans. No signup required.
await page.screenshot({
path: 'region.png',
clip: {
x: 100,
y: 200,
width: 800,
height: 450,
},
});A clip can extend beyond the current viewport. Puppeteer documents captureBeyondViewport as true by default when a clip is supplied and false when there is no clip. Set it explicitly when you need predictable behavior:
await page.screenshot({
path: 'region.png',
clip: { x: 0, y: 0, width: 800, height: 450 },
captureBeyondViewport: true,
});Element-sized capture
For a component, read its bounding box and pass the values to clip:
Rank #3
const box = await page.locator('.invoice').boundingBox();
if (!box) throw new Error('Invoice element is not visible');
await page.screenshot({ path: 'invoice.png', clip: box });Make sure animations, sticky headers, and fonts have settled before measuring. A missing box usually means the selector is wrong, the element is hidden, or it has not rendered yet.
Control format and image quality
PNG, JPEG and WebP
PNG is lossless and is Puppeteer’s default. Select another format explicitly:
await page.screenshot({ path: 'photo.jpg', type: 'jpeg', quality: 85 });
await page.screenshot({ path: 'photo.webp', type: 'webp', quality: 80 });quality ranges from 0 to 100 and applies to lossy formats, not PNG. It changes compression and visual fidelity, not viewport dimensions or device-pixel density. Puppeteer can also infer the type from a .png, .jpg, or .webp path, but specifying type makes scripts clearer.
Reusable resolution presets
Keep layout and density choices explicit so jobs are reproducible:
const presets = {
desktop: { width: 1440, height: 900, deviceScaleFactor: 1 },
retina: { width: 1440, height: 900, deviceScaleFactor: 2 },
mobile: { width: 390, height: 844, deviceScaleFactor: 3 },
};
await page.setViewport(presets.retina);
await page.goto('https://example.com', { waitUntil: 'networkidle0' });
await page.screenshot({ path: 'retina.webp', type: 'webp', quality: 82 });The mobile preset changes CSS breakpoints because its width is 390 CSS pixels; DSF 3 affects density only. If you emulate mobile or touch explicitly, configure those values before navigation.
Common mistakes and fixes
The file is the wrong pixel size
Check all four variables: viewport width and height, DSF, whether fullPage was enabled, and whether a clip was supplied. A 1280×720 CSS viewport at DSF 2 is not a 1280×720-pixel file.
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 problemsRank #4
- Brand: Wiley
- Set of 2 Volumes
- A handy two-book set that uniquely combines related technologies Highly visual format and accessible language makes these books highly effective learning tools Perfect for beginning web designers and front-end developers
The page uses the wrong responsive layout
Set the viewport before goto. Confirm the width in CSS pixels and avoid changing mobile or touch settings after the page has loaded, because Puppeteer may reload during that change.
Full-page output is blank or incomplete
Wait for the application’s ready condition, not merely the first HTML response. Use a selector wait, a deliberate delay for known client rendering, or an appropriate network-idle condition. For lazy content, scroll or otherwise trigger loading before capture.
JPEG quality appears to do nothing
Quality is ignored for PNG. Choose type: 'jpeg' or type: 'webp', then set a value from 0 to 100.
The clipped region is offset or missing
clip coordinates are CSS-pixel coordinates in the page. Recalculate the element’s bounding box after layout settles, and verify that x, y, width, and height are non-negative and finite.
Memory or timeout failures on long pages
Reduce DSF, capture sections with separate clips, or use a viewport shot when a full document is unnecessary. Wait for a bounded readiness condition and close each browser instance in a finally block in production code. Large full-page images and high-density PNGs consume substantially more memory than smaller or lossy captures.
Performance, determinism and cost considerations
- Density: higher DSF improves fine detail but increases raster work, memory use and transfer size.
- Area: full-page captures cost more time and memory than viewport or small clip captures.
- Encoding: PNG preserves exact pixels; JPEG/WebP can reduce storage when some loss is acceptable.
- Readiness: waiting for a stable application state prevents fast but unusable screenshots.
- Repeatability: fix viewport, DSF, timezone, fonts, animations and network conditions when comparing screenshots.
Or skip the browser setup
ScreenshotNeo provides a screenshot API and MCP server when you do not want to maintain Puppeteer launch, viewport and waiting code. One GET request returns PNG, JPEG, WebP or PDF. Before capture it accepts cookie or consent banners and removes more than 60 known consent platforms, newsletter popups and chat widgets; each cleanup step can be disabled. Bot checks, CAPTCHAs, blank pages, timeouts, failed loads and cache hits are not billed, and response headers report the page verdict and billing status.
It supports full-page and CSS-selector captures, dark mode, 12 device presets or custom viewports, retina scale, PDF paper and page controls, custom CSS and JavaScript, pre-capture clicks, selector or network-idle waits, request and resource blocking, headers, cookies, user agents, authorization, timezone, geolocation, transparent backgrounds, resizing, configurable-TTL caching, signed image links, asynchronous webhooks, bulk capture of up to 100 URLs per call, a usage API and an OpenAPI specification. Parameter names used by other screenshot APIs also work.
For AI workflows, its MCP server exposes take_screenshot, get_page_info and capture_pdf to Claude, Cursor and other MCP clients. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots. See the ScreenshotNeo documentation for request options.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpimport requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);Create a free ScreenshotNeo account to use the 1,000 monthly screenshots without a card.
FAQ
Does increasing screenshot quality increase resolution?
No. Quality changes lossy compression; viewport dimensions and device scale factor determine pixel density.
Can I make a full-page screenshot exactly 1920 pixels tall?
Not by setting viewport height alone. Full-page height follows document content. Use a clip or resize the result when an exact output height is required.
What is the default device scale factor?
Puppeteer documents a default of 1; setting it to 0 resets to the system default.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Should I use PNG or WebP for visual regression tests?
PNG avoids lossy encoding differences. WebP or JPEG is more appropriate when compact files matter more than exact pixel equality.
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.
