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
- Create a project directory – Make a folder for your work, e.g.,
selenium-screenshots. - Create a Dockerfile – Inside that folder, create a file named
Dockerfile. Use a Python base image with Chrome and Chromedriver pre-installed. Theselenium/standalone-chromeimage is a good starting point, but for a lightweight custom setup, usepython:3.11-slimand install Chrome manually. - Install dependencies – In the Dockerfile, run
apt-get updateand installwget,unzip, andfonts-liberation(for proper text rendering). Then download the latest stable Chrome .deb package and install it. Also install Chromedriver viapip install seleniumor download it separately. - 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 usedriver.get(url)anddriver.save_screenshot('output.png'). - 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. - Run the container – Execute
docker run --rm -v $(pwd):/app selenium-shot python /app/capture.py. The-vflag mounts your current directory so the screenshot is saved to your host machine. - Verify the output – Check that
output.pngexists 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/shmsize in Docker is small (64MB), which can cause Chrome to crash on complex pages. This flag makes Chrome use/tmpinstead. - 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. Usetime.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,1080for desktop views. For full-page captures, usedriver.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
/appso 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-sliminstead oflatestto avoid unexpected changes in future builds. - Consider using a pre-built image – The
selenium/standalone-chromeimage 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
- How to Factory Reset iPad If You Forgot Password
- Ubuntu in Windows Store: Which Editions Work?
- Secure Guest Account on Windows 11: Step-by-Step
- Stop Outlook From Changing Hyperlink Font
- Hiberfil.sys: What It Is & How to Delete It
- How to Make a Mask on Snapchat: Step-by-Step