October DealsAmazon USOctober deal check: compare before you payAmazon US: current deals, useful picks and tech finds.Check DealsWindows FixRecommendedWindows errors stealing your time? Find the fix fastScan stability, cleanup and performance issues.Fix NowOctober DealsAmazon USDeal season is back - check today's better picksAmazon US: current deals, useful picks and tech finds.See Picks×
Skip to content
World desk6 min

How to Capture a Webpage Screenshot with Puppeteer in Docker

A practical Puppeteer-in-Docker guide with runnable screenshot code, the official image invocation, capture options, sandbox guidance and fixes for common container errors.
Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Use Puppeteer’s Page.screenshot() in a Node.js script, run it in a container with Chrome and its Linux dependencies, and mount an output directory so the image is available on the host. Puppeteer’s official Docker image includes Chrome for Testing and is designed to run Chrome sandboxed; its documented setup requires Docker’s SYS_ADMIN capability and uses --init. The example below captures a full-page PNG after navigation.

Capture a page with Puppeteer

Create a script such as screenshot.js that navigates to the target page, captures it and closes the browser even if an operation fails:

As an Amazon Associate I earn from qualifying purchases.

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: '/output/page.png', fullPage: true });
  } finally {
    await browser.close();
  }
})();

networkidle2 is Puppeteer’s documented example navigation condition, not a guarantee that every site has finished rendering everything you want. For pages that render content after navigation, use a page-specific readiness condition such as waiting for a selector before the screenshot. The output path in this example is inside the container; the Docker command below mounts it to a host directory.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

The Puppeteer screenshot guide, displayed as version 25.12.0 when accessed on October 3, 2026, documents page and element screenshots. A full-page capture uses the fullPage option; omit it when you only need the current viewport.

Run the script in Puppeteer’s Docker image

Puppeteer’s Docker guide describes an image with Chrome for Testing, required dependencies and a preinstalled Puppeteer version. Its instructions say the image is intended to run Chrome sandboxed and requires SYS_ADMIN. They also use --init to manage processes started by Puppeteer.

mkdir -p output
docker run --init --cap-add=SYS_ADMIN --rm 
  -v "$PWD/output:/output" 
  ghcr.io/puppeteer/puppeteer:latest 
  node /app/screenshot.js

Adjust /app/screenshot.js to the script’s actual location in the image you use. The mount makes the container’s /output directory available as the host’s local output directory, where you should find page.png after a successful run.

The official Docker page is labeled “Next,” and the latest image tag can change. For repeatable builds, choose and pin an image tag matching the Puppeteer release you intend to run, then verify the current tags and instructions in the Puppeteer Docker guide.

Free tools Windows power users keep installed

One-click scans. No signup required.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Choose the right capture scope and readiness check

Viewport or full page

Use page.screenshot() for a page capture. Set fullPage: true when you need the full document rather than the visible viewport. A full-page capture does not itself guarantee that lazy-loaded images or other delayed content have appeared; wait for the relevant content before capturing.

One element

When you only need a component, wait for its selector and capture its element instead of the whole page:

const element = await page.waitForSelector('.product-card');
if (!element) throw new Error('Product card was not found');
await element.screenshot({ path: '/output/product-card.png' });

Puppeteer’s element screenshot method scrolls a hidden element into view by default. Choose a selector that uniquely identifies the component you need.

Navigation completion versus page readiness

The navigation condition answers a browser lifecycle question; it cannot know whether a particular site has finished client-side rendering, animation or data loading. If a screenshot is blank or misses content, wait for the site’s meaningful selector or state before calling screenshot(), rather than assuming a network-idle event is sufficient.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Build a custom container when needed

If you cannot use Puppeteer’s supplied image, start from its Dockerfile or use a supported Linux environment and install the shared libraries required by the Chrome build. Puppeteer normally downloads a compatible Chrome for Testing browser during installation. If your package manager blocks install scripts, permit Puppeteer’s install script or install the browser explicitly with npx puppeteer browsers install. The installation guide displayed version 25.12.0 when accessed on October 3, 2026; it estimates the Linux Chrome for Testing download at approximately 282 MB, an install-size estimate rather than a runtime memory requirement. See Puppeteer installation and Puppeteer troubleshooting.

Use puppeteer-core if you manage the browser separately. In that case, configure an explicit executable path or channel for the browser you provide. Ensure the browser version and dependencies are compatible with your Puppeteer setup.

Keep the browser sandbox and writable paths in mind

Prefer keeping Chrome’s sandbox enabled, especially if the script may visit pages you do not control. The Puppeteer image expects sandboxed Chrome and documents the SYS_ADMIN capability. Puppeteer’s troubleshooting guidance describes --no-sandbox only for trusted page content and explicitly discourages treating it as a general fix. Disabling the sandbox for a service that browses arbitrary URLs changes its security posture.

In custom images or read-only container environments, Chrome may also need writable configuration, cache, profile and output locations. Run as a non-root browser user where appropriate, make its browser cache and output directories writable by that user, and set XDG_CONFIG_HOME, XDG_CACHE_HOME or Puppeteer’s userDataDir to writable paths when the defaults are not available.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Troubleshoot common Docker errors

Symptom Likely cause What to check or change
Chrome fails to launch because a shared library is missing The custom image lacks a Linux library required by the selected Chrome build. Install the required dependencies for your base image and browser version using Puppeteer’s troubleshooting guidance.
Could not find Chrome The package manager or build environment blocked Puppeteer’s postinstall browser download, or no browser was installed. Allow the Puppeteer install script or run npx puppeteer browsers install. If you manage Chrome separately, configure the executable path or channel.
Profile, crashpad or read-only filesystem startup failure Chrome cannot write browser state to its default location. Provide writable configuration and cache paths, set a writable userDataDir, or mount browser-state directories owned by the runtime user.
Zombie Chrome processes after the script exits Child processes are not being reaped by the container’s process setup. Use Docker’s --init option or a suitable init entrypoint, as in Puppeteer’s documented Docker invocation.
Sandbox startup error The runtime may not have the sandbox configuration or capability expected by the selected image. Check the image’s sandbox requirements and configure the container accordingly; do not disable the sandbox by default.
Chrome does not work on Alpine Puppeteer’s troubleshooting page cautions that Chrome does not work on Alpine out of the box. Choose compatible system dependencies and browser versions, and validate the exact image/browser combination. Do not rely on a time-sensitive workaround without checking it against your current setup.
The image exists but the expected screenshot is missing on the host The script may write somewhere other than the mounted path, or the host directory may not be mounted as expected. Write to the container path in the volume mount (here, /output) and check the corresponding host directory (here, ./output).
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Support on Ko-Fi

Or skip the browser setup

If you need a screenshot without maintaining a Puppeteer container, ScreenshotNeo is a website screenshot API and MCP server. A GET request with a URL returns a PNG, JPEG, WebP or PDF. For example, this cURL request saves a WebP screenshot:

Best Value
Docker Container Linux Devops Programming Coding T-Shirt
  • Docker, Docker Swarm, Docker Compose, Programmer, Developer, Coding, Programming, Software Engineer, Code, DevOps, Deploy, Deployment, Kubernetes, Salt, Puppet, Chef, Terraform, Container, AWS, Azure, Cloud, Geek, Funny, Computer, Software, Tech, IT
  • Integration, Scrum, Compile, Compilation, Science, Bug, Debug, Python, Linux, Java, Javascript, Scala, Dotnet, Kotlin
  • Lightweight, Classic fit, Double-needle sleeve and bottom hem
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com -o shot.webp

See the ScreenshotNeo API documentation for request options. ScreenshotNeo removes cookie and consent banners, newsletter popups and chat widgets before capture; these steps can be turned off. Bot checks, blank pages, timeouts, failed loads and cache hits are not billed, and response headers identify the page verdict and billing status. Its MCP server offers take_screenshot, get_page_info and capture_pdf for Claude, Cursor and other MCP clients. The Free plan includes 1,000 shots per month with no card; paid plans start at $5 for 3,000 shots.

Sign up for ScreenshotNeo’s free plan to get 1,000 screenshots a month with no card.

Frequently Asked Questions

Can I save a screenshot from a Docker container to my computer?

Yes. Mount a host directory into the container and write the screenshot to the corresponding container path, such as /output/page.png in the example.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Does Puppeteer’s Docker image require disabling Chrome’s sandbox?

No. The documented image is designed for sandboxed Chrome and requires SYS_ADMIN; Puppeteer discourages using --no-sandbox as a general configuration.

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.

Leave a Reply

Your email address will not be published. Required fields are marked *

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

More from the Wire

  1. World desk4 min
    How to Spot an AI Voice Scam Before Sending MoneyDon’t rely on how a caller sounds. Pause, call back through a known number, and verify the emergency with another trusted person before sending money.
  2. Mountain View desk4 min
    Google’s SynthID Detector: How to Check AI-Generated Images, Video and AudioGoogle’s SynthID Detector looks for an embedded watermark in supported images, video and audio. Here is what its results do—and do not—show.
  3. Redmond desk20 min
    How to create a link to File or Folder in Windows 11Windows 11 gives you several ways to point to a file or folder without moving or duplicating it. You can create a desktop shortcut,…
Recommended PC Tool
Recommended PC Tool
Windows Errors? Fix Them Before They SpreadFree repair scan
Crashes, No Sound, or Screen Glitches?Free driver scan

Two free Windows tools

One Free Minute Could Fix That PC

Before you go - each of these free tools takes about a minute and tackles what quietly slows a Windows PC down.

Special offer. View Outbyte info, uninstall instructions, EULA, and Privacy Policy.