October DealsAmazon USOctober deal check: compare before you payAmazon US: current deals, useful picks and tech finds.Check DealsWindows FixRecommendedWindows errors stealing your time? Find the fix fastScan stability, cleanup and performance issues.Fix NowOctober DealsAmazon USDeal season is back - check today's better picksAmazon US: current deals, useful picks and tech finds.See Picks×
Skip to content
AWS EC2

How to Deploy Puppeteer on AWS EC2: Install, Configure, and Troubleshoot

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

To deploy Puppeteer on EC2, install your Node.js app and its dependencies on a Linux instance, ensure a compatible Chrome browser and its Linux libraries are available to the account that runs the app, then verify a browser launch before putting the service into production. The simplest browser setup is to install the standard puppeteer package, which downloads a compatible Chrome for Testing browser during installation. A successful npm install alone does not prove Chrome can start: missing system libraries, inaccessible browser files, and sandbox configuration can still prevent launch.

This guide uses Ubuntu Server 24.04 LTS as the example AMI. Package names and commands below are for that distribution; they are not Amazon Linux instructions. AWS connection usernames and requirements vary by AMI and connection method.

Choose an EC2 image and a safe way to connect

Pick the AMI before following package commands. This walkthrough assumes an Ubuntu Server 24.04 LTS AMI and uses Ubuntu’s apt package manager. Puppeteer’s Linux requirements vary by distribution, and AWS user-data examples also warn that Amazon Linux commands may not work unchanged on other distributions.

For initial setup, you can connect over SSH with a key pair or use EC2 Instance Connect when the instance and account meet its prerequisites. Neither method removes the need to configure network access appropriately. For production, do not expose SSH to every IPv4 address; restrict inbound port 22 to an administrator’s IP range or use a supported connection method configured with its required IAM, network, and instance prerequisites. See AWS’s EC2 Instance Connect requirements and SSH connection guidance.

What’s actually slowing this PC down?

Pick the symptom - the matching free tool is one click away.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
  1. Wait until the EC2 instance status checks pass. Note its public address or other reachable address and confirm the security group permits your chosen connection.
  2. For SSH, use the private key associated with the instance’s key pair. Set the key file’s local permissions appropriately for your SSH client.
  3. Use the login name for the AMI. AWS lists ubuntu for Ubuntu and ec2-user for Amazon Linux; other images may use different names. Its connection prerequisites and connection troubleshooting pages cover common checks.
  4. Connect with SSH, replacing the example address and key path with your own:
    ssh -i /path/to/key.pem ubuntu@EC2_PUBLIC_IP

Do not assume that EC2 Instance Connect is simply SSH without a key. Check AWS’s documented prerequisites for your selected image and connection setup.

Install Node.js, Puppeteer, and its browser

Puppeteer is the JavaScript automation library; Chrome is a separate runtime that Puppeteer controls. The Puppeteer project describes it as “a JavaScript library which provides a high-level API to control Chrome or Firefox over the DevTools Protocol or WebDriver BiDi.” The standard puppeteer package downloads a compatible Chrome for Testing browser during installation. If you deliberately manage Chrome separately, configure Puppeteer to use that browser’s executable and keep its version compatible with the installed Puppeteer release. See the Puppeteer installation guide.

Install a Node.js version supported by the Puppeteer version your app uses, following the Node.js distribution’s current instructions for Ubuntu 24.04. This guide does not pin a Node.js or Puppeteer release: both change over time, and no live deployment or version validation is claimed here. Record the exact versions selected in your project lockfile and deployment documentation.

  1. In your application directory, add Puppeteer as an application dependency:
    npm install puppeteer
  2. Commit the generated lockfile. During deployment, use npm ci in the same project directory to install the locked dependency tree reproducibly.
  3. Check the install output for the browser download. If your deployment environment intentionally skips install scripts or browser downloads, make the browser installation step explicit and confirm its executable path.

Ensure the account that installs the dependency and downloads Chrome is compatible with the account that runs the service. If those users differ, check that the runtime user can read and execute the browser and access the configured Puppeteer cache. Puppeteer’s configuration guide describes browser installation and cache configuration.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Install Ubuntu 24.04 browser libraries

Chrome relies on operating-system shared libraries in addition to the browser files. Puppeteer’s troubleshooting guide lists Linux dependencies and recommends using ldd to identify missing shared libraries. Install dependencies appropriate to your actual AMI; do not paste Debian-family package names into Amazon Linux commands or assume package availability is identical across Ubuntu releases.

For Ubuntu Server 24.04 LTS, begin by refreshing apt metadata and installing the common runtime libraries listed for Debian/Ubuntu-family Chrome deployments in Puppeteer’s Linux guidance. Package availability can depend on enabled repositories and image updates, so verify the set against the selected AMI if apt reports a missing package.

sudo apt-get update
sudo apt-get install -y ca-certificates fonts-liberation libasound2t64 libatk-bridge2.0-0 libatk1.0-0 libc6 libcairo2 libcups2 libdbus-1-3 libdrm2 libexpat1 libgbm1 libgcc-s1 libglib2.0-0 libnspr4 libnss3 libpango-1.0-0 libx11-6 libx11-xcb1 libxcb1 libxcomposite1 libxdamage1 libxext6 libxfixes3 libxrandr2 libxrender1 libxshmfence1 libstdc++6 libxss1 libxtst6

This package command is labeled for Ubuntu Server 24.04 LTS only; it is not a generic Linux or Amazon Linux recipe. If Chrome reports a missing shared library, use the executable actually configured for Puppeteer and inspect its dependencies:

ldd /path/to/chrome | grep "not found"

Replace /path/to/chrome with the resolved Chrome executable path. Install the Ubuntu package that provides each missing library, then repeat the check. If the output contains no “not found” entries, ldd has not identified unresolved shared libraries; that does not by itself guarantee the browser can launch successfully.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Run a minimal launch check as the service user

Before exposing an application or scheduling browser jobs, run a small task as the same operating-system account and in the same environment as the deployed service. This catches differences in browser cache, permissions, environment variables, and profile directories. The example below is a small project smoke test, not a deployment test performed for this article.

Save as smoke-test.js in the project directory:

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch();
  try {
    const page = await browser.newPage();
    await page.goto('https://example.com', { waitUntil: 'domcontentloaded' });
    console.log('Title:', await page.title());
  } finally {
    await browser.close();
  }
})().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

Run it as the account that will actually execute the app, for example with sudo -u appuser -H node smoke-test.js if your service account is named appuser. The command assumes Node.js and the project dependencies are accessible to that user. A successful run should print the page title and exit; failures should be diagnosed before relying on the browser in production.

Choose a repeatable deployment method

Manual setup

Manual SSH setup is useful for a first instance or a short-lived experiment, but it is easy for the package state to drift. Keep a written record of the AMI ID or release, Node.js version, Puppeteer lockfile, browser source, installed system libraries, and service account. Rebuild instructions should work on a fresh instance rather than relying on undocumented changes.

EC2 user data

EC2 user data can run shell scripts or cloud-init configuration during launch. AWS notes that its user-data examples assume Amazon Linux and may not work on other distributions; adapt commands to the chosen image and validate them against that AMI generation. Do not use an Amazon Linux package command in an Ubuntu script. For more substantial infrastructure configuration, AWS points to CloudFormation. See EC2 user data.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

A launch script should be designed for the instance lifecycle you actually use. Some user-data execution patterns run only on first boot; if you expect repeated execution, ensure the steps are safe to rerun and do not overwrite application data or create conflicting users. Keep secrets out of scripts that may be exposed through instance metadata or configuration records.

Browser management choices

Approach Advantages Checks to make
Install puppeteer and use its downloaded Chrome for Testing Browser version is selected to be compatible with the Puppeteer install. Install scripts must run; browser cache must be available to runtime user; deployment artifact or instance must have enough space for browser files.
Install and manage a system browser separately Browser lifecycle can follow an operating-system or organization package process. Set Puppeteer’s executable selection correctly, document the exact browser version and path, and verify compatibility when either browser or Puppeteer changes.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Support on Ko-Fi

Troubleshoot “Chrome failed to launch” on Linux

Work from the exact error and the runtime account’s environment rather than adding launch flags at random.

Chrome is missing or the configured path is wrong

  • Check whether Puppeteer’s installation script ran and whether its expected Chrome exists in the configured cache.
  • If using a system-managed browser, confirm the executable path supplied to Puppeteer points to that installed binary.
  • Check that deployment did not install Puppeteer as one user and run the app as another user without sharing the browser cache.

The browser file or profile directory is inaccessible

Verify read and execute permissions on the Chrome executable and its parent directories. Confirm the runtime account can create and use its browser profile and temporary files. Puppeteer launch options include an executable selection and user-data-directory setting; use a writable profile location appropriate for the service rather than sharing a profile between concurrent jobs.

A shared library is missing

Run ldd against the configured Chrome executable and look for lines ending in not found. Install the missing library through the package manager for the selected AMI, then rerun the check. Consult Puppeteer’s distribution-specific Linux dependency notes rather than copying an Amazon Linux example onto Ubuntu or assuming a legacy Amazon Linux command applies to a current release.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

The error mentions the Chrome sandbox

Chrome uses multiple sandbox layers. Read the full error and address the instance’s security and execution configuration. Puppeteer documents --no-sandbox only for cases where the operator absolutely trusts the content being loaded; it is not a harmless default for a public-facing scraper or service. Do not disable the sandbox merely to suppress a launch error. See the security discussion in the Puppeteer troubleshooting guide.

SSH cannot connect

  • Confirm instance status checks have passed and that you are using a reachable address.
  • Check the AMI-specific username: Ubuntu commonly uses ubuntu; Amazon Linux commonly uses ec2-user.
  • Confirm the key pair and local private-key path are correct, and that the inbound rule permits the source address on port 22.
  • If using EC2 Instance Connect, confirm its IAM, network, and instance prerequisites rather than troubleshooting it as ordinary key-based SSH.

Plan for reliability, performance, and cost

Browser automation consumes memory, CPU, temporary storage, and network capacity. The exact requirements depend on the pages, concurrency, browser options, and workload; the sources here establish no universal instance size or performance benchmark. Start with the workload you intend to run and monitor memory pressure, process exits, launch time, and disk use. Limit concurrent browser processes to what the instance can sustain, close pages and browsers in cleanup paths, and ensure temporary profiles do not accumulate indefinitely.

Keep browser upgrades intentional: a change to Puppeteer can change its compatible browser download, while a separately managed browser can drift independently. Pin application dependencies with a lockfile and validate a browser launch after dependency, AMI, or library changes. For recurring services, automate the setup and smoke check so a replacement instance can be brought up consistently.

Or skip the browser setup

If you only need screenshots or PDFs rather than a browser process you manage, ScreenshotNeo provides a website screenshot API and MCP server. One GET request can return a PNG, JPEG, WebP, or PDF. Cookie banners, newsletter popups, and chat widgets are removed before capture; bot checks, blank pages, and failed loads are not billed. Its MCP server lets AI agents use screenshot tools, and its free plan includes 1,000 screenshots a month without a card; paid plans start at $5 for 3,000 screenshots.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Here is the one-call cURL example; see the ScreenshotNeo API documentation for request options:

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com -o shot.webp

Sign up for 1,000 free screenshots a month with no card.

Frequently Asked Questions

Can I use this Ubuntu package command on Amazon Linux?

No. The apt packages shown are for Ubuntu Server 24.04 LTS. Use package instructions verified for your specific Amazon Linux release.

Does EC2 Instance Connect require the same setup as SSH with a private key?

No. AWS documents separate IAM, network, and instance prerequisites for EC2 Instance Connect.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.

Leave a Reply

Your email address will not be published. Required fields are marked *

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Read next

Recommended PC Tool
Recommended PC Tool
Outdated Drivers Are Slowing You DownFree scan - exact matches
PC Slower Than It Used to Be?Free scan - under a minute

Two free Windows tools

One Free Minute Could Fix That PC

Before you go - each of these free tools takes about a minute and tackles what quietly slows a Windows PC down.

Special offer. View Outbyte info, uninstall instructions, EULA, and Privacy Policy.