Puppeteer Screenshot Image Formats: PNG, JPEG, and WebP

Puppeteer supports three screenshot image formats: png, jpeg, and webp. PNG is the documented default. Set type explicitly when you want JPEG or WebP, and set quality from 0 to 100 for JPEG or WebP; that option does not apply to PNG. If you save to a path, make the filename extension agree with the format you request.

The examples below use Puppeteer’s documented Page.screenshot() API. The API details cited here are from the Puppeteer 25.12.0 reference; check the documentation for the version installed in your project. See the ScreenshotOptions reference, ImageFormat reference, and screenshot guide.

1. Supported formats and how to choose

Format	Puppeteer support	When to choose it
PNG	Supported; documented default	Use when the receiving system expects PNG or when you have not selected another format. PNG is also the format to consider when transparency is required, but verify the output behavior in the environment that will consume it.
JPEG	Supported	Choose it when your downstream service or workflow requires JPEG. You can set quality from 0 to 100.
WebP	Supported	Choose it when your downstream service or workflow accepts WebP. You can set quality from 0 to 100.

The official Puppeteer references establish supported names and options, but do not rank these formats by file size, visual fidelity, encoding speed, or compatibility. There is no universal best format or quality value in those references. Check what your receiving system accepts, then capture representative pages and compare the resulting file weight and appearance for your use case.

2. Complete Node.js examples

Install Puppeteer in your project with npm install puppeteer. Save one of the following examples as a JavaScript file and run it with Node.js. Each example launches Chromium, captures a page, and closes the browser even if capture fails.

Save a PNG

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch();
  try {
    const page = await browser.newPage();
    await page.goto('https://example.com', { waitUntil: 'networkidle2' });
    await page.screenshot({ path: 'capture.png', type: 'png' });
  } finally {
    await browser.close();
  }
})();

PNG is the default, so type: 'png' is optional here. Keeping it explicit can make the intended format clear during maintenance.

Save a JPEG with a chosen quality

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch();
  try {
    const page = await browser.newPage();
    await page.goto('https://example.com', { waitUntil: 'networkidle2' });
    await page.screenshot({
      path: 'capture.jpg',
      type: 'jpeg',
      quality: 80
    });
  } finally {
    await browser.close();
  }
})();

Save a WebP with a chosen quality

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch();
  try {
    const page = await browser.newPage();
    await page.goto('https://example.com', { waitUntil: 'networkidle2' });
    await page.screenshot({
      path: 'capture.webp',
      type: 'webp',
      quality: 80
    });
  } finally {
    await browser.close();
  }
})();

The quality value above is an example, not a universal recommendation or benchmark. Compare values using your own pages and delivery requirements. Puppeteer documents the range as 0–100 and says it does not apply to PNG.

3. Format, extension, quality, and transparency options

Option	Meaning	Practical guidance
type	Image format: 'png', 'jpeg', or 'webp'. The documented default is 'png'.	Set it when you need JPEG or WebP. For readable code, set it explicitly when format is important.
path	Output file path. Puppeteer documents that it infers the screenshot type from the file extension when a path is given.	Pair type: 'jpeg' with a .jpg or .jpeg filename, and type: 'webp' with .webp. Keep the requested type and extension consistent to avoid confusion for people and downstream tools.
quality	A number from 0 to 100; not applicable to PNG.	Use it with JPEG or WebP, then inspect both visual results and file sizes on representative content. The API reference does not prescribe a quality target.
omitBackground	Defaults to false. When enabled, it hides the default white background and allows capture with transparency.	Use omitBackground: true when transparency is needed, and confirm that the selected format and your consuming software preserve it as expected. The consulted references do not compare transparency behavior across all three formats.
encoding	Controls the returned data representation ('base64' or 'binary'), separately from the image format.	Do not use it to select PNG, JPEG, or WebP; use type for that.

Capture with a transparent background

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch();
  try {
    const page = await browser.newPage();
    await page.setContent('<div style="font: 32px sans-serif; color: navy">Transparent capture</div>');
    await page.screenshot({
      path: 'transparent.png',
      type: 'png',
      omitBackground: true
    });
  } finally {
    await browser.close();
  }
})();

This option hides the browser’s default white background; page content can still paint its own backgrounds. If transparency is essential, inspect the saved file in the destination workflow instead of assuming every format and viewer handles it identically.

4. Choose a format with a repeatable check

1. List the formats accepted by the destination: an upload endpoint, image pipeline, document, or browser client.
2. Decide whether the capture needs a transparent background. If so, enable omitBackground and validate the resulting file in the consumer.
3. Capture the same representative page with each format your destination accepts. Use matching explicit type and path values.
4. For JPEG and WebP, compare several quality values in the documented 0–100 range. PNG does not use the quality option.
5. Check the actual output dimensions, file size, and visual appearance. Keep the format and settings that meet your delivery constraints.
6. Record the selected format and quality alongside the capture pipeline so future changes do not silently alter output expectations.

This is a local evaluation procedure, not a claim that one format will always be smaller, sharper, or faster. Results depend on the page and the consumers in your pipeline.

5. Common errors and fixes

Symptom	Likely cause	Fix
The file is PNG although JPEG or WebP was expected.	type was omitted, so the documented default applied, or the path extension indicates another format.	Set type explicitly and make the output extension agree, such as type: 'webp' with capture.webp.
The file has an unexpected extension or a downstream decoder rejects it.	The requested type and filename extension do not agree, or the receiver expects a different format.	Use a matching extension and format, and check the receiver’s accepted formats. Avoid renaming a file as a substitute for encoding it in another format.
Changing quality has no effect on a PNG capture.	Puppeteer documents quality as not applicable to PNG.	For a quality-controlled capture, select JPEG or WebP and test values from 0 to 100.
The output is opaque despite omitBackground: true.	Page content may paint its own background, or the chosen format or viewer may not preserve or display transparency as expected.	Remove page-level backgrounds if appropriate, use omitBackground: true, and inspect the output in the actual consuming workflow. The cited references do not specify cross-format transparency comparisons.
The screenshot call fails before an image is written.	Navigation or capture may have failed, or the process may not be able to write to the requested path.	Check the full exception, confirm the destination directory exists and is writable, and separate page navigation from screenshot capture when diagnosing the failure.
The captured page is incomplete.	The page may still be rendering or loading assets when capture starts.	Choose an appropriate navigation wait condition or wait for a page-specific selector or delay before calling screenshot(). A fixed network-idle condition may not match every site’s behavior.

6. Performance, reliability, and cost

The cited Puppeteer format references do not provide comparative encoding benchmarks, so measure your own pages if file weight or capture time matters. Reuse browser processes where your application architecture permits instead of launching one browser for every image, and always close pages or browsers on success and failure. Set sensible navigation timeouts and wait for the condition your target page needs; pages with long-lived network activity may not reach network idle predictably.

For reliability, make output paths unique when running concurrent captures, check that the file was written, and validate the image with the same decoder or upload service that consumes it. A successful screenshot API call does not guarantee that a later system accepts the chosen encoding or extension.

With self-hosted Puppeteer, account for the compute and storage used by Chromium and the generated files in your own environment; the research sources provide no cost figures. If you would rather avoid managing browser setup, ScreenshotNeo offers a one-request screenshot API and an MCP server. Its plans are Free for 1,000 shots per month with no card, Starter $5 for 3,000, Growth $15 for 15,000, Pro $39 for 60,000, Scale $99 for 250,000, and Business $249 for 1,000,000; yearly billing gives two months free, and every feature is on every plan.

7. Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server for developers. One GET request returns a PNG, JPEG, WebP, or PDF. See the ScreenshotNeo site and API documentation.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import 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}`);

• Cookie and consent banners, newsletter popups, and chat widgets are removed before capture; each step can be turned off.
• Bot checks, blank pages, failed loads, timeouts, and cache hits are never billed. Responses include X-Page-Verdict and X-Billed headers.
• An MCP server provides take_screenshot, get_page_info, and capture_pdf tools for AI agents, including Claude, Cursor, and other MCP clients.
• 1,000 screenshots per month are free with no card; paid plans start at $5 for 3,000.

Sign up free for 1,000 screenshots a month, with no card.

8. FAQ

Can I use jpg as the value for type?

The documented Puppeteer format values are png, jpeg, and webp. Use 'jpeg' for the type, even if the output filename uses the common .jpg extension.

Does encoding: 'base64' make the screenshot a different image format?

No. Encoding controls how screenshot data is returned; type selects PNG, JPEG, or WebP.

Does Puppeteer recommend a quality value?

The cited API reference gives a 0–100 range for quality and says it does not apply to PNG. It does not recommend a universal value.

Where can I verify the options for my installed Puppeteer version?

Check the version-specific ScreenshotOptions API reference and the screenshot guide.