Save Puppeteer Screenshots as GIF, JP2, TIFF, AVIF, HEIF, or SVG
Puppeteer saves still screenshots as PNG, JPEG, or WebP. Learn what to do when you need GIF, JP2, TIFF, AVIF, HEIF, or SVG.
Short answer: Puppeteer’s documented still-screenshot formats are PNG, JPEG, and WebP. It does not directly save still screenshots as GIF, JP2, TIFF, AVIF, HEIF, or SVG. Capture a supported format first, then convert it with a separate encoder that supports your target format.
A filename extension does not encode the image. Renaming page.png to page.avif, for example, leaves PNG data in the file. Puppeteer’s current screenshot API reference documents version 25.12.0; check the reference for your installed version if format behavior matters. Puppeteer screenshot options
1. What formats does Puppeteer support directly?
The documented screenshot type is 'png' | 'jpeg' | 'webp'. PNG is the default. A screenshot can be saved to a path or returned as bytes or base64, depending on the options. When a path is supplied, Puppeteer says the type is inferred from its extension, within the supported image formats. That behavior does not add a new encoder. ScreenshotOptions API reference
| Requested format | Direct still screenshot? | What to do |
|---|---|---|
| GIF | No | Capture PNG, JPEG, or WebP, then use a GIF-capable encoder. Puppeteer lists GIF separately as a video format; that is not still-screenshot support. Screenshot options · Video options |
| JP2 | No | Convert the captured image with a JP2-capable encoder. |
| TIFF | No | Convert with a TIFF-capable encoder. |
| AVIF | No | Convert with an encoder that supports AVIF. |
| HEIF | No | Convert with a compatible HEIF encoder. |
| SVG | No | Screenshot output is raster pixels. A separately constructed SVG may embed a raster image, but does not make those pixels vector artwork. |
The Puppeteer reference documents the API boundary; encoder availability, native dependencies, transparency behavior, color handling, and conversion settings depend on the separate tool and environment you choose. Verify the actual output format and test it in the application that will consume it.
2. Save a Puppeteer screenshot in a supported format
Install Puppeteer in a Node.js project using its official installation guide. The following complete example opens a page and saves 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: 'page.png', type: 'png', fullPage: true });
} finally {
await browser.close();
}
})();Run it with node screenshot.js. For an image Puppeteer supports directly, set type to 'png', 'jpeg', or 'webp'; keep the filename extension consistent. The official guide also documents ElementHandle.screenshot() for capturing one selected element; it scrolls the element into view if it is hidden. Puppeteer screenshots guide
Relevant screenshot options
path: save the capture to disk. If omitted, the screenshot data is returned.type: choose PNG, JPEG, or WebP. PNG is the default.quality: applies to JPEG and WebP; it is not applicable to PNG. Check the installed version’s API reference for the accepted range and behavior.fullPage: capture the full page rather than only the viewport.clip: capture a specified rectangular region.omitBackground: omit the default background where supported, useful when transparency is needed.encoding: return base64 instead of binary data when requested. Binary bytes are generally the more direct choice for saving or passing image data to another process.
Consult the installed version’s screenshot options for the full option list and exact types.
3. Convert to GIF, JP2, TIFF, AVIF, HEIF, or SVG
Keep capture and conversion as two explicit steps:
- Capture a PNG, JPEG, or WebP with Puppeteer.
- Pass the resulting file or bytes to a separate tool that documents support for the target format.
- Check that the deployed runtime includes that encoder and any required native dependencies.
- Inspect the output’s actual format, then open it in the destination application.
This guide does not prescribe a particular converter: the available evidence establishes Puppeteer’s screenshot formats, not which third-party encoder works for a given platform or deployment. Check the converter’s own current documentation for supported formats, options, and installation requirements.
Format-specific points
- GIF: Puppeteer’s API mentions GIF in its video options, but not as a still screenshot type. A single-frame GIF requires a separate conversion step; animation requires multiple frames and a workflow that assembles them.
- JP2 and TIFF: Neither appears in the documented screenshot image type. Use a separate encoder and verify its output in the intended consumer.
- AVIF and HEIF: Neither is listed as a direct screenshot type. An external encoder must support the requested format in the runtime where conversion runs.
- SVG: Screenshot pixels are raster data. An SVG wrapper can contain a raster image, but it does not trace the page into editable vector shapes. Actual vector output requires a separate reconstruction or tracing process.
4. Choosing a capture format before conversion
There is no universal best intermediate format based on the documented Puppeteer API. Choose based on what your encoder accepts and what the destination needs. Compare the produced files for visual fidelity, file size, transparency and color behavior, and compatibility with the consumer. Results depend on page content, encoder, and settings; do not assume a format will always be smaller or look better.
- Use PNG as a straightforward lossless capture source when your conversion workflow accepts it.
- Use JPEG or WebP when those formats suit the capture and conversion pipeline; their quality option does not apply to PNG.
- Keep the original supported-format capture if you need a reproducible source for later conversion.
5. Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
The API rejects type: 'avif' (or another requested target). |
The requested format is not in Puppeteer’s documented still screenshot type. | Capture PNG, JPEG, or WebP, then convert with a separate compatible encoder. |
A file named image.tiff is identified as PNG. |
The extension was changed, but the image bytes were not converted. | Run a real encoder conversion and verify the resulting file format. |
| GIF appears available in Puppeteer documentation, but screenshot output is not GIF. | GIF is listed separately as a video format, not as a still screenshot type. | Use a still-image conversion workflow, or a separate frame-assembly workflow for animation. |
| Quality settings have no effect on PNG. | Puppeteer documents quality as inapplicable to PNG. |
Use a supported lossy type where suitable, or configure quality in the external encoder. |
| Conversion works locally but fails in deployment. | The converter or its native encoder dependency may be absent or configured differently in the deployed runtime. | Check the converter’s installation instructions and verify target-format support in the actual deployment image. |
| An SVG file opens but is not editable as vector artwork. | It may only wrap or embed the raster screenshot. | Use a real vector reconstruction or tracing workflow if editable vector shapes are required. |
| The capture contains a loading state or incomplete page. | The page may need a different navigation condition or an explicit application-specific readiness check. | Wait for the page or relevant element to be ready before capturing; see Puppeteer’s screenshots guide and navigation documentation. |
6. Performance, reliability, and cost
For a conversion pipeline, total latency and resource use include browser startup, page loading, screenshot encoding, and the separate conversion step. Full-page captures can involve more page content than viewport captures. Measure the workflow with your pages, output settings, and deployment environment; the referenced Puppeteer sources provide no comparative benchmark for these target formats.
For reliability, keep capture and conversion failures distinguishable in logs, retain a supported-format source when practical, and validate output files before passing them to downstream systems. Check the converter’s own documentation for memory use, concurrency limits, native dependencies, and supported options. Puppeteer’s screenshot documentation does not establish those converter-specific details or a universal cost comparison.
7. Or skip the browser setup
ScreenshotNeo provides a website screenshot API and MCP server for developers. Its API returns screenshots in PNG, JPEG, or WebP, or a PDF; it does not turn the requested GIF, JP2, TIFF, AVIF, HEIF, or SVG into direct screenshot formats. If one of its supported image formats works for your use case, a single GET request can capture a URL. See the ScreenshotNeo API documentation.
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}`);- Cookie banners and consent prompts, newsletter popups, and chat widgets are removed before the shot; each cleanup step can be turned off.
- Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing. Response headers report the page verdict and whether the request was billed.
- An MCP server provides
take_screenshot,get_page_info, andcapture_pdftools for AI agents and MCP clients. - 1,000 screenshots a month are free with no card; paid plans start at $5 for 3,000 screenshots. Every feature is on every plan.
Create a free ScreenshotNeo account to get 1,000 screenshots a month with no card.
8. FAQ
Can changing the screenshot filename make Puppeteer write AVIF or TIFF?
No. A suffix does not add encoding support. Use a real converter after capture.
Can I use an SVG file if it embeds a PNG screenshot?
You can construct an SVG that contains a raster image, but the screenshot remains raster content rather than editable vector artwork.
Does Puppeteer’s GIF video option mean it can save a still screenshot as GIF?
No. The documented video format and still screenshot image type are separate API concepts.
Should I choose PNG, JPEG, or WebP as the conversion source?
Choose based on the converter’s inputs and your needs for fidelity, file size, transparency, and compatibility. Compare actual outputs for your content and settings.
Could a future Puppeteer version add one of these formats?
Possibly. The documented reference cited here lists PNG, JPEG, and WebP; check the API reference matching the version installed in your project.
