DEV Community

Cover image for How to use Puppeteer inside a Docker container
Axel Navarro for Cloud(x);

Posted on

How to use Puppeteer inside a Docker container


Puppeteer is a Node.js library which provides a high-level API to control Chromium (or Firefox) browsers over the DevTools Protocol.

This guide helps to use Puppeteer inside a Docker container using the Node.js image.

If we use the Docker images for Node.js v14 LTS Gallium, when installing the chromium package from apt, it will be v90.0, which can have compatibility issues with the latest Puppeteer. This is because it was tested with the latest Chromium stable release.

Selecting the correct image

Well... we want to run a web browser inside a container. it's important to know what are the different between the available variants.

Alpine is enough but ...

Yeah, we can run Chromium using Alpine Linux, but we'll need a few extra steps to make it run. That's why we prefer Debian variants to make it easier.

Which distro?

Every major version of Node.js in built over a version of Debian, and that Debian version comes with an old version of Chromium, which one could be not compatible with the latest version of Puppeteer.

Node.js Debian Chromium
v14 9.13 73.0.3683.75
v16 10.9 90.0.4430.212
v17 11.2 99.0.4844.84

To quickly solve that issue we can use the Google Chrome's Debian package that always installs the latest stable version. Therefore, this Dockerfile is compatible with Node.js v14, v16, or any new one.

Why not the built-in Chromium

When we install Google Chrome, apt will install all the dependencies for us.


FROM node:slim AS app

# We don't need the standalone Chromium

# Install Google Chrome Stable and fonts
# Note: this installs the necessary libs to make the browser work with Puppeteer.
RUN apt-get update && apt-get install curl gnupg -y \
  && curl --location --silent | apt-key add - \
  && sh -c 'echo "deb [arch=amd64] stable main" >> /etc/apt/sources.list.d/google.list' \
  && apt-get update \
  && apt-get install google-chrome-stable -y --no-install-recommends \
  && rm -rf /var/lib/apt/lists/*

# Install your app here...
Enter fullscreen mode Exit fullscreen mode

The code config

Remember to use the installed browser instead of the Puppeteer's built-in one inside your app's code.

import puppeteer from 'puppeteer';

const browser = await puppeteer.launch({
  executablePath: '/usr/bin/google-chrome',
  args: [...] // if we need them.
Enter fullscreen mode Exit fullscreen mode


The browser installation via apt will resolve the required dependencies to run a headless browser inside a Docker container without any manual intervention. These dependencies are not included in the Node.js Docker images by default.

The easiest path to use Puppeteer inside a Docker container is installing Google Chrome because, in contrast to the Chromium package offered by Debian, Chrome only offers the latest stable version.

Discussion (3)

evanstjabadi profile image
Evans Tjabadi

@navarroaxel - nice article - helped me even though I am using the python version

brassel profile image
Captain Fim • Edited on

When I try to use the docker file above to build an image, I get

#5 7.862 E: Unable to locate package google-chrome-stable

navarroaxel profile image
Axel Navarro Author • Edited on

Works for me using this Dockerfile, I built it with

docker build --tag node-chrome .
Enter fullscreen mode Exit fullscreen mode

Are you using another base image instead of FROM node:slim AS app?