sodcalculator

10 Tech How-To

Docker Headless Chrome Selenium Screenshots

Guide 10-55692 · Updated · Step by step

This guide walks you through capturing screenshots with Selenium in a Docker container using headless Chrome. You’ll get a reproducible setup that works in CI/CD pipelines or server environments where no display is available. You’ll need Docker installed, basic familiarity with the command line, and a small Python or Node.js script.

What You’ll Need

  • Docker installed on your machine (Docker Desktop on Windows/Mac, or Docker Engine on Linux)
  • A text editor to create the Dockerfile and script
  • Basic knowledge of Selenium WebDriver (Python or JavaScript)
  • Internet access to pull base images and install packages

Step-by-Step

  1. Create a project directory – Make a folder for your work, e.g., selenium-screenshots.
  2. Create a Dockerfile – Inside that folder, create a file named Dockerfile. Use a Python base image with Chrome and Chromedriver pre-installed. The selenium/standalone-chrome image is a good starting point, but for a lightweight custom setup, use python:3.11-slim and install Chrome manually.
  3. Install dependencies – In the Dockerfile, run apt-get update and install wget, unzip, and fonts-liberation (for proper text rendering). Then download the latest stable Chrome .deb package and install it. Also install Chromedriver via pip install selenium or download it separately.
  4. Write the screenshot script – Create a Python file (e.g., capture.py) that uses Selenium. Set Chrome options to run headless: options.add_argument('--headless'), --no-sandbox, --disable-dev-shm-usage, and --window-size=1920,1080. Then use driver.get(url) and driver.save_screenshot('output.png').
  5. Build the Docker image – Run docker build -t selenium-shot . from the project directory. This will install all dependencies and copy your script into the image.
  6. Run the container – Execute docker run --rm -v $(pwd):/app selenium-shot python /app/capture.py. The -v flag mounts your current directory so the screenshot is saved to your host machine.
  7. Verify the output – Check that output.png exists in your project folder and open it to confirm the page rendered correctly.

Common Mistakes

  • Forgetting --no-sandbox – Chrome in Docker often fails to start without this flag because of root user restrictions. Always include it.
  • Not setting --disable-dev-shm-usage – The default /dev/shm size in Docker is small (64MB), which can cause Chrome to crash on complex pages. This flag makes Chrome use /tmp instead.
  • Using a full-screen window size – If you don’t set --window-size, headless Chrome defaults to 800×600, which may cut off content. Set an explicit size like 1920×1080.
  • Not waiting for page load – Screenshots taken immediately after get() may capture a blank or partially loaded page. Use time.sleep() or WebDriverWait for elements to appear.
  • Running as root without sandbox – Even with --no-sandbox, you may need to create a non-root user in the Dockerfile to avoid permission issues with Chrome’s user data directory.

Tips

  • Use a larger window size for full-page screenshots – Set --window-size=1920,1080 for desktop views. For full-page captures, use driver.set_window_size() after loading the page to match the content height.
  • Add a small delay – A 1-2 second wait after page load ensures fonts and images are rendered. For dynamic content, use explicit waits with expected conditions.
  • Use a volume mount for output – Always mount a host directory to /app so screenshots persist after the container exits. Otherwise, they’re lost when the container is removed.
  • Pin your base image version – Use a specific tag like python:3.11-slim instead of latest to avoid unexpected changes in future builds.
  • Consider using a pre-built image – The selenium/standalone-chrome image already has Chrome and Chromedriver configured, saving build time. You just need to install your script dependencies.

Troubleshooting

Chrome doesn’t start – If you see an error like “Failed to move to new namespace” or “DevToolsActivePort file doesn’t exist”, add --no-sandbox and --disable-dev-shm-usage to your options. Also ensure you’re not running as root without these flags.

Blank screenshot – This usually means the page didn’t load. Check your URL is accessible from inside the container (try curl in the container). Add a wait or increase the timeout. Also ensure you’re not using localhost – use host.docker.internal if you need to reach a service on your host.

Chromedriver version mismatch – If you get a “session not created” error, your Chromedriver version doesn’t match the Chrome browser version. Use a pre-built image that bundles both, or download the exact matching Chromedriver in your Dockerfile.

Permission denied when saving screenshot – The container user may not have write access to the mounted volume. Run the container with --user $(id -u):$(id -g) or set the directory permissions on the host.

Memory issues – If Chrome crashes with “Out of memory”, increase the Docker container memory limit (e.g., --memory=2g) or reduce the number of concurrent tabs.

Frequently Asked Questions

Q: Can I use this with JavaScript instead of Python? – Yes. Use a Node.js base image, install selenium-webdriver, and write a similar script. The Chrome options are the same.

Q: How do I take a screenshot of a specific element? – Use element.screenshot('filename.png') in Python after locating the element with driver.find_element().

Q: Can I capture full-page screenshots? – Yes, but it requires extra steps. Set a large window size, then use driver.execute_script("return document.body.scrollHeight") to get the height and resize the window accordingly. Some tools like Selenium’s built-in save_screenshot() only capture the viewport.

Q: Why does my screenshot look different from my local browser? – Headless Chrome may render fonts differently or lack certain system fonts. Install common fonts like fonts-liberation and ttf-mscorefonts-installer in the Dockerfile to improve consistency.

Q: Is it safe to run Chrome as root in Docker? – It works with --no-sandbox, but it’s not recommended for security. Create a non-root user in your Dockerfile and switch to it before running Chrome.

Q: Can I run multiple screenshots in parallel? – Yes, but be mindful of memory. Use a pool of workers or run containers with --memory limits. Alternatively, use Selenium Grid to distribute across multiple containers.

Related

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 →