Headless Chrome doesn't launch on Windows
Some Chrome policies might enforce running Chrome or Chromium with certain Extensions.
Puppeteer passes --disable-extensions
flag by default, and therefore it fails
to launch when such policies are active.
To work around this, try running without the flag:
const browser = await puppeteer.launch({
ignoreDefaultArgs: ['--disable-extensions'],
});
Context: issue 3681.
Headless Chrome doesn't launch on UNIX
Make sure all the necessary dependencies are installed. You can run
ldd chrome | grep not
on a Linux machine to check which dependencies are
missing.
Debian (Ubuntu) dependencies
ca-certificates
fonts-liberation
libappindicator3-1
libasound2
libatk-bridge2.0-0
libatk1.0-0
libc6
libcairo2
libcups2
libdbus-1-3
libexpat1
libfontconfig1
libgbm1
libgcc1
libglib2.0-0
libgtk-3-0
libnspr4
libnss3
libpango-1.0-0
libpangocairo-1.0-0
libstdc++6
libx11-6
libx11-xcb1
libxcb1
libxcomposite1
libxcursor1
libxdamage1
libxext6
libxfixes3
libxi6
libxrandr2
libxrender1
libxss1
libxtst6
lsb-release
wget
xdg-utils
CentOS Dependencies
alsa-lib.x86_64
atk.x86_64
cups-libs.x86_64
gtk3.x86_64
ipa-gothic-fonts
libXcomposite.x86_64
libXcursor.x86_64
libXdamage.x86_64
libXext.x86_64
libXi.x86_64
libXrandr.x86_64
libXScrnSaver.x86_64
libXtst.x86_64
pango.x86_64
xorg-x11-fonts-100dpi
xorg-x11-fonts-75dpi
xorg-x11-fonts-cyrillic
xorg-x11-fonts-misc
xorg-x11-fonts-Type1
xorg-x11-utils
After installing dependencies you need to update nss library using this command
yum update nss -y
Check out discussions:
Headless Chrome disables GPU compositing
Chrome and Chromium requires --use-gl=egl
to enable
GPU acceleration in headless mode.
const browser = await puppeteer.launch({
headless: true,
args: ['--use-gl=egl'],
});
Chrome is downloaded but fails to launch on Node.js
If you get an error that looks like this when trying to launch Chromium:
(node:15505) UnhandledPromiseRejectionWarning: Error: Failed to launch the browser process!
spawn /Users/.../node_modules/puppeteer/.local-chromium/mac-756035/chrome-mac/Chromium.app/Contents/MacOS/Chromium ENOENT
This means that the browser was downloaded but failed to be extracted correctly.
The most common cause is a bug in Node.js v14.0.0 which broke extract-zip
,
the module Puppeteer uses to extract browser downloads into the right place. The
bug was fixed in Node.js v14.1.0, so make sure you're running that version or
higher.
Set up a Chrome Linux sandbox
In order to protect the host environment from untrusted web content, Chrome uses
multiple layers of sandboxing.
For this to work properly, the host should be configured first. If there's no
good sandbox for Chrome to use, it will crash with the error No usable sandbox!
.
If you absolutely trust the content you open in Chrome, you can launch
Chrome with the --no-sandbox
argument:
const browser = await puppeteer.launch({
args: ['--no-sandbox', '--disable-setuid-sandbox'],
});
There are 2 ways to configure a sandbox in Chromium.
[recommended] Enable user namespace cloning
Sser namespace cloning is only supported by modern kernels. Unprivileged user namespaces are generally fine to enable, but can open up more kernel attack surface for (unsandboxed) non-root processes to elevate to kernel privileges.
sudo sysctl -w kernel.unprivileged_userns_clone=1
[alternative] Setup setuid sandbox
The setuid sandbox comes as a standalone executable and is located next to the Chromium that Puppeteer downloads. It's fine to re-use the same sandbox executable for different Chromium versions, so the following could be done only once per host environment:
# cd to the downloaded instance
cd <project-dir-path>/node_modules/puppeteer/.local-chromium/linux-<revision>/chrome-linux/
sudo chown root:root chrome_sandbox
sudo chmod 4755 chrome_sandbox
# copy sandbox executable to a shared location
sudo cp -p chrome_sandbox /usr/local/sbin/chrome-devel-sandbox
# export CHROME_DEVEL_SANDBOX env variable
export CHROME_DEVEL_SANDBOX=/usr/local/sbin/chrome-devel-sandbox
You might want to export the CHROME_DEVEL_SANDBOX
env variable by default. In this case, add the following to the ~/.bashrc
or .zshenv
:
export CHROME_DEVEL_SANDBOX=/usr/local/sbin/chrome-devel-sandbox
Run Puppeteer on Travis CI
We ran our tests for Puppeteer on Travis CI until v6.0.0, after which we
migrated to GitHub Actions. You can see
.travis.yml
(v5.5.0)
for reference.
Here are some best practices:
- xvfb service should be launched to run Chromium in non-headless mode
- Runs on Xenial Linux on Travis by default
- Runs
npm install
by default node_modules
is cached by default
.travis.yml
might look like this:
language: node_js
node_js: node
services: xvfb
script:
- npm run test
Run Puppeteer on CircleCI
- Start with a NodeJS image in your config.
yaml docker: - image: circleci/node:14 # Use your desired version environment: NODE_ENV: development # Only needed if puppeteer is in `devDependencies`
- Dependencies like
libXtst6
probably need to be installed withapt-get
, so use the threetreeslight/puppeteer orb (instructions), or paste parts of its source into your own config. - Lastly, if you're use Puppeteer through Jest, then you may encounter an
error spawning child processes:
shell [00:00.0] jest args: --e2e --spec --max-workers=36 Error: spawn ENOMEM at ChildProcess.spawn (internal/child_process.js:394:11)
This is likely caused by Jest auto-detecting the number of processes on the entire machine (36
) rather than the number allowed to your container (2
). To fix this, setjest --maxWorkers=2
in your test command.
Run Puppeteer in Docker
Getting headless Chrome up and running in Docker can be tricky. The bundled Chromium that Puppeteer installs is missing the necessary shared library dependencies.
To fix, you'll need to install the missing dependencies and the latest Chromium package in your Dockerfile:
FROM node:14-slim
# Install latest chrome dev package and fonts to support major charsets (Chinese, Japanese, Arabic, Hebrew, Thai and a few others)
# Note: this installs the necessary libs to make the bundled version of Chromium that Puppeteer
# installs, work.
RUN apt-get update \
&& apt-get install -y wget gnupg \
&& wget -q -O - https://dl-ssl.google.com/linux/linux_signing_key.pub | apt-key add - \
&& sh -c 'echo "deb [arch=amd64] http://dl.google.com/linux/chrome/deb/ stable main" >> /etc/apt/sources.list.d/google.list' \
&& apt-get update \
&& apt-get install -y google-chrome-stable fonts-ipafont-gothic fonts-wqy-zenhei fonts-thai-tlwg fonts-kacst fonts-freefont-ttf libxss1 \
--no-install-recommends \
&& rm -rf /var/lib/apt/lists/*
# If running Docker >= 1.13.0 use docker run's --init arg to reap zombie processes, otherwise
# uncomment the following lines to have `dumb-init` as PID 1
# ADD https://github.com/Yelp/dumb-init/releases/download/v1.2.2/dumb-init_1.2.2_x86_64 /usr/local/bin/dumb-init
# RUN chmod +x /usr/local/bin/dumb-init
# ENTRYPOINT ["dumb-init", "--"]
# Uncomment to skip the chromium download when installing puppeteer. If you do,
# you'll need to launch puppeteer with:
# browser.launch({executablePath: 'google-chrome-stable'})
# ENV PUPPETEER_SKIP_CHROMIUM_DOWNLOAD true
# Install puppeteer so it's available in the container.
RUN npm init -y && \
npm i puppeteer \
# Add user so we don't need --no-sandbox.
# same layer as npm install to keep re-chowned files from using up several hundred MBs more space
&& groupadd -r pptruser && useradd -r -g pptruser -G audio,video pptruser \
&& mkdir -p /home/pptruser/Downloads \
&& chown -R pptruser:pptruser /home/pptruser \
&& chown -R pptruser:pptruser /node_modules \
&& chown -R pptruser:pptruser /package.json \
&& chown -R pptruser:pptruser /package-lock.json
# Run everything after as non-privileged user.
USER pptruser
CMD ["google-chrome-stable"]
Build the container:
docker build -t puppeteer-chrome-linux .
Run the container by passing node -e "<yourscript.js content as a string>"
as the command:
docker run -i --init --rm --cap-add=SYS_ADMIN \
--name puppeteer-chrome puppeteer-chrome-linux \
node -e "`cat yourscript.js`"
There's a full example at https://github.com/ebidel/try-puppeteer that shows how to run this Dockerfile from a web server running on App Engine Flex (Node).
Run on Alpine
The newest Chromium package supported on Alpine is 100, which corresponds to Puppeteer v13.5.0.
Example Dockerfile:
FROM alpine
# Installs latest Chromium (100) package.
RUN apk add --no-cache \
chromium \
nss \
freetype \
harfbuzz \
ca-certificates \
ttf-freefont \
nodejs \
yarn
...
# Tell Puppeteer to skip installing Chrome. We'll be using the installed package.
ENV PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true \
PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium-browser
# Puppeteer v13.5.0 works with Chromium 100.
RUN yarn add puppeteer@13.5.0
# Add user so we don't need --no-sandbox.
RUN addgroup -S pptruser && adduser -S -G pptruser pptruser \
&& mkdir -p /home/pptruser/Downloads /app \
&& chown -R pptruser:pptruser /home/pptruser \
&& chown -R pptruser:pptruser /app
# Run everything after as non-privileged user.
USER pptruser
...
Best practices with Docker
By default, Docker runs a container with a /dev/shm
shared memory space 64MB.
This is typically too small
for Chrome and will cause Chrome to crash when rendering large pages. To fix,
run the container with docker run --shm-size=1gb
to increase the size of
/dev/shm
. Since Chrome 65, this is no longer necessary. Instead, launch the
browser with the --disable-dev-shm-usage
flag:
const browser = await puppeteer.launch({
args: ['--disable-dev-shm-usage'],
});
This writes shared memory files into /tmp
instead of /dev/shm
. Review
crbug.com/736452.
Do you see other weird errors when launching Chrome? Try running your container
with docker run --cap-add=SYS_ADMIN
when developing locally. Since the
Dockerfile adds a pptr
user as a non-privileged user, it may not have all the
necessary privileges.
dumb-init is worth checking out if you're
experiencing a lot of zombies Chrome processes sticking around. There's special
treatment for processes with PID=1
, which makes it hard to terminate Chrome
properly in some cases (such as with Docker).
Run Puppeteer in the cloud
On Google App Engine
The Node.js runtime of the App Engine standard environment comes with all system packages needed to run Headless Chrome.
To use puppeteer
, list the module as a dependency in your package.json
and
deploy to Google App Engine. Read more about using puppeteer
on App Engine by
following the official tutorial.
On Google Cloud Functions
The Node.js 10 runtime of Google Cloud Functions comes with all system packages needed to run Headless Chrome.
To use puppeteer
, list the module as a dependency in your package.json
and
deploy your function to Google Cloud Functions using the nodejs10
runtime.
Run Puppeteer on Google Cloud Run
The default Node.js runtime of
Google Cloud Run does not come with the
system packages needed to run Headless Chrome. Set up your own Dockerfile
and
include the missing dependencies.
On Heroku
Running Puppeteer on Heroku requires some additional dependencies that aren't included on the Linux box that Heroku spins up for you. To add the dependencies on deploy, add the Puppeteer Heroku buildpack to the list of buildpacks for your app under Settings > Buildpacks.
The URL for the buildpack is https://github.com/jontewks/puppeteer-heroku-buildpack
Ensure that you use '--no-sandbox'
mode when launching Puppeteer. This can be
done by passing it as an argument to your .launch()
call:
puppeteer.launch({ args: ['--no-sandbox'] });
.
When you click add buildpack, paste that URL into the input, and click save. On the next deploy, your app will also install the dependencies that Puppeteer needs to run.
If you need to render Chinese, Japanese, or Korean characters you may need to use a buildpack with additional font files like https://github.com/CoffeeAndCode/puppeteer-heroku-buildpack
There's also another guide from @timleland that includes a sample project.
On AWS Lambda
AWS Lambda limits deployment package sizes to ~50MB. This presents challenges for running headless Chrome (and therefore Puppeteer) on Lambda. The community has put together a few resources that work around the issues:
- Chromium Binary for AWS Lambda and Google Cloud Functions (kept updated with the latest stable release of Puppeteer)
- Chrome/Chromium on AWS Lambda from Marco Lüthy is a serverless plugin and is outdated.
AWS EC2 instance running Amazon-Linux
If you have an EC2 instance running amazon-linux in your CI/CD pipeline, and you want to run Puppeteer tests in amazon-linux, follow these steps.
To install Chromium, you must first enable
amazon-linux-extras
, which is part of EPEL (Extra Packages for Enterprise Linux):sudo amazon-linux-extras install epel -y
Next, install Chromium:
sudo yum install -y chromium
Now Puppeteer can launch Chromium to run your tests. If you don't enable EPEL
and continue installing Chromium as part of npm install
, Puppeteer cannot
launch Chromium due to unavailability of libatk-1.0.so.0
and many more packages.
Code transpilation issues
If you are using a JavaScript transpiler like babel or TypeScript, calling
evaluate()
with an async function might not work. This is because while
puppeteer
uses Function.prototype.toString()
to serialize functions while
transpilers could be changing the output code in such a way it's incompatible
with puppeteer
.
Some workarounds to this problem would be to instruct the transpiler not to mess
up with the code, for example, configure TypeScript to use latest ecma version
("target": "es2018"
). Another workaround could be using string templates
instead of functions:
await page.evaluate(`(async() => {
console.log('1');
})()`);