Chrome Headless Screenshots in Docker: Step-by-Step

This guide shows you how to capture full-page or viewport screenshots of any website using headless Chrome inside a Docker container. You’ll end up with a reproducible setup that works on any machine with Docker installed, perfect for CI pipelines, monitoring, or generating preview images.

What You’ll Need

Docker installed and running (Docker Desktop or a Linux Docker engine).
Basic familiarity with the command line.
A URL you want to screenshot (public or accessible from the container).
Optional: a directory on your host to save the screenshots.

Step-by-Step

Pull the official Chrome image. The simplest way is to use the chromium image from Docker Hub, which is maintained by the Chromium project. Run:
```
docker pull chromium/chromium
```
This gives you a lightweight Linux image with Chromium (the open-source base of Chrome) pre-installed.
Run a test screenshot. Use the following command to capture a screenshot of example.com and save it to your current directory:
```
docker run --rm -v "$PWD":/screenshots chromium/chromium chromium --headless --no-sandbox --disable-gpu --screenshot=/screenshots/example.png --window-size=1280,800 https://example.com
```
- --rm removes the container after it exits.
- -v "$PWD":/screenshots mounts your current folder into the container so the file is written to your host.
- --no-sandbox is required because running as root inside a container disables the usual sandbox.
- --disable-gpu avoids GPU-related issues in headless mode.
- --screenshot specifies the output path.
- --window-size sets the viewport size.
Verify the screenshot. After the command finishes, check that example.png exists in your current directory. Open it to confirm it shows the page correctly.

Capture a full-page screenshot. By default, Chrome only captures the visible viewport. To get the entire page height, add the --screenshot flag with the --full-page option:

docker run --rm -v "$PWD":/screenshots chromium/chromium chromium --headless --no-sandbox --disable-gpu --screenshot=/screenshots/fullpage.png --window-size=1280,800 --full-page https://example.com

Set a custom user agent and device emulation. To mimic a mobile device or specific browser, pass the --user-agent flag and adjust the window size:

docker run --rm -v "$PWD":/screenshots chromium/chromium chromium --headless --no-sandbox --disable-gpu --screenshot=/screenshots/mobile.png --window-size=375,812 --user-agent="Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1" https://example.com

Add a delay for dynamic content. Many sites load content via JavaScript after the initial render. Use the --virtual-time-budget flag to give the page time to settle:
```
docker run --rm -v "$PWD":/screenshots chromium/chromium chromium --headless --no-sandbox --disable-gpu --screenshot=/screenshots/delayed.png --virtual-time-budget=5000 https://example.com
```
The value is in milliseconds, so 5000 = 5 seconds.

Create a reusable script. Instead of typing the long command each time, save a shell script (e.g., screenshot.sh) with the following content:

#!/bin/bash
URL="${1:-https://example.com}"
OUT="${2:-screenshot.png}"
WIDTH="${3:-1280}"
HEIGHT="${4:-800}"
docker run --rm -v "$PWD":/screenshots chromium/chromium chromium --headless --no-sandbox --disable-gpu --screenshot=/screenshots/$OUT --window-size=$WIDTH,$HEIGHT --virtual-time-budget=3000 "$URL"

Make it executable with chmod +x screenshot.sh and run it: ./screenshot.sh https://example.com myimage.png.

Build a custom Dockerfile (optional). If you need additional fonts, certificates, or tools, create a Dockerfile:

FROM chromium/chromium
RUN sudo apk add --no-cache ttf-freefont  # for Alpine-based image
WORKDIR /screenshots
ENTRYPOINT ["chromium", "--headless", "--no-sandbox", "--disable-gpu"]

Build with docker build -t my-chrome . and then run:

docker run --rm -v "$PWD":/screenshots my-chrome --screenshot=/screenshots/custom.png https://example.com

Common Mistakes

Forgetting --no-sandbox: Without it, Chrome crashes with a sandbox error because the container runs as root.
Not mounting a volume: If you omit -v, the screenshot is written inside the container and lost when the container exits.
Using the wrong image name: The official image is chromium/chromium, not chrome or google-chrome. The latter may not exist or may be outdated.
Expecting full-page by default: Without --full-page, you only get the viewport height.
Not waiting for JavaScript: Many modern sites need a few seconds to load content; without --virtual-time-budget, you may get a blank or partial page.

Tips

Use --hide-scrollbars to remove scrollbars from the screenshot.
For a specific format (JPEG, WebP), add --screenshot-format=jpeg or webp.
Set a higher --window-size for retina-like captures, then scale down with an image tool if needed.
If you need to log in or interact with the page, consider using Puppeteer or Selenium in a custom container instead of the basic CLI.
Use a named volume instead of a bind mount if you want to avoid permissions issues on Windows.
Run the container with --shm-size=1g if you encounter crashes on complex pages (shared memory issues).

Troubleshooting

Error: “Failed to move to new namespace” – This usually means the sandbox is not disabled. Add --no-sandbox to the command.
Blank or white screenshot – The page likely needs more time to render. Increase --virtual-time-budget to 10000 or more. Also check that the URL is accessible from inside the container (try curl inside the container).
Permission denied when writing the screenshot – The mounted directory may not be writable by the container’s user. Run the container with --user $(id -u):$(id -g) or change the directory permissions.
Certificate errors on HTTPS sites – Add --ignore-certificate-errors if you’re testing a site with a self-signed certificate, but do not use this in production.
Container exits immediately with no output – Check the URL is correct and reachable. Run the container without --rm to see logs, or add --dump-dom to verify the page loads.
High CPU or memory usage – Some pages are heavy. Limit resources with --memory=512m --cpus=1 in the docker run command.

Frequently Asked Questions

Is this the same as Google Chrome?

Chromium is the open-source project that Google Chrome is built from. For screenshots, the behavior is essentially identical. If you specifically need Google Chrome (e.g., for proprietary codecs), you can install it manually in a custom image, but Chromium covers most use cases.

Can I take a screenshot of a page that requires login?

Yes, but you need to handle authentication. Options include passing cookies via the --user-data-dir flag with a pre-authenticated profile, or using a tool like Puppeteer to script the login process before capturing.

How do I change the output file format?

Add --screenshot-format=jpeg or webp to the command. The default is PNG. Note that JPEG does not support transparency.

Why is my screenshot cut off at the bottom?

You’re likely not using --full-page. Without it, Chrome captures only the viewport height. Add that flag to capture the entire page length.

Can I run multiple screenshots in parallel?

Yes, you can run multiple docker run commands in parallel, but be mindful of CPU and memory usage. For large batches, consider using a script that runs them sequentially or with limited concurrency.

How do I take a screenshot of a local HTML file?

Mount the directory containing the file and use a file:// URL, e.g., file:///screenshots/index.html. Ensure the file has read permissions for the container user.

General steps for current mainstream versions; menus can differ by device and version. See the disclaimer or report an error.

More in this bed

The whole Tech How-To bed →