How to Run Playwright on AWS EC2

Direct answer: Connect to a Linux EC2 instance, install your application dependencies, then install the Playwright browser binaries and required Linux packages. For an npm project, the core setup is npm ci followed by npx playwright install --with-deps. Playwright runs headlessly by default, so ordinary server-side tests do not need a desktop or virtual display.

This guide uses an npm project on Linux. Your exact AMI, CPU architecture, Node.js version, and Playwright version depend on your application. Browser binaries are tied to Playwright releases, so install browsers after installing or updating the package version used by your project. See the official Playwright browser documentation and CI documentation.

1. Create and connect to a Linux EC2 instance

EC2 provides a virtual server in AWS. Choose a Linux AMI and instance size based on your application and test workload; there is no universally correct instance type or performance target for every Playwright suite.

Connect using an access method supported by your account and instance. AWS documents SSH, EC2 Instance Connect, and Systems Manager Session Manager. These options have different requirements: SSH commonly uses a key pair and inbound network rules, while other methods depend on their configured IAM permissions and instance setup. Follow the method that is enabled for your environment in the AWS EC2 connection guide.

Once connected, check the operating system and architecture so you can use package instructions appropriate to that machine:

uname -a
cat /etc/os-release

2. Install the project and Playwright browsers

Run these commands from the project directory on the EC2 instance. This example assumes the repository has a committed npm lockfile and lists Playwright as a project dependency.

node --version
npm --version
npm ci
npx playwright install --with-deps

npm ci installs the dependency versions recorded in the lockfile. The Playwright install command downloads the browser binaries that match the installed Playwright package and, with --with-deps, installs required Linux system dependencies. Run it after selecting the project’s Playwright version; updating Playwright can require installing browser binaries again.

Install only the browser engines you need

If your project does not use every browser engine, you can install a specific one and its system dependencies. Choose the engine names supported by the Playwright CLI:

npx playwright install --with-deps chromium
npx playwright install --with-deps firefox
npx playwright install --with-deps webkit

Use the same Playwright package version when installing browsers and running tests. The browser guide also documents installing operating-system dependencies separately with the CLI when that fits your image-building process better.

3. Run tests headlessly

Playwright launches browsers in headless mode by default. Run your project’s test command, for example:

npx playwright test

A minimal Playwright Test configuration can make the intended browser project explicit. Save as playwright.config.js:

import { defineConfig } from '@playwright/test';

export default defineConfig({
  testDir: './tests',
  use: {
    headless: true,
  },
  projects: [
    {
      name: 'chromium',
      use: { browserName: 'chromium' },
    },
  ],
});

If your project uses CommonJS, adapt the configuration module syntax to match its package setup. The headless setting is shown for clarity; it is already the default.

4. Run headed tests with a virtual display

Use headed mode only when you need a visible browser session, such as when diagnosing behavior that depends on a graphical environment. Linux servers generally do not have a physical display. Playwright’s CI guidance uses Xvfb, a virtual display server, for headed Linux execution.

xvfb-run npx playwright test --headed

This gives the browser a virtual display; it does not attach a monitor to the EC2 instance. If you need to interact with a full desktop, a vendor-preconfigured GUI image is another possible route, but marketplace listings and their terms can vary. Review the current listing and its requirements before relying on one.

5. Use a repeatable deployment workflow

For a stable setup, keep the package lockfile in source control and run browser installation as part of instance provisioning or image creation. A basic deployment sequence is:

Launch or select the Linux instance and connect using an AWS-supported access method.
Install the Node.js runtime version required by the project.
Check out the project revision and run npm ci.
Run npx playwright install --with-deps for the pinned package version.
Run npx playwright test and retain the exit code and logs in your job output.

When you update the Playwright dependency, rerun browser installation in the environment that will execute the tests. This avoids a mismatch between the package and cached browser binaries.

6. Troubleshoot common failures

Symptom	Likely cause	What to do
Browser executable not found	The browser binary was not installed for the current Playwright package, or the package version changed after installation.	From the project directory, run `npx playwright install` or `npx playwright install --with-deps`, then rerun the test.
Browser fails to launch due to a missing shared library	A required Linux system dependency is absent.	Run `npx playwright install --with-deps` on the target image and inspect the launch error for the missing library name.
Tests work locally but fail on EC2	The server may have a different OS, architecture, runtime, environment configuration, or browser installation.	Compare the project version and runtime, verify the browser installation happened on the target system, and inspect the first browser launch error.
Headed browser reports no display	Headed Linux execution has no graphical display available.	Use default headless mode, or run headed tests under `xvfb-run`.
Browser launch hangs or exits early	There may be an installation, environment, or resource issue; the research sources do not establish a universal EC2 sizing fix.	Enable browser launch logs with `DEBUG=pw:browser`, inspect the output, then verify dependencies and evaluate whether the selected instance fits the workload.
Package install fails before tests start	The runtime or package manager may not match the project requirements, or the lockfile may be missing or inconsistent.	Use the Node.js version expected by the project and restore a valid committed lockfile before running `npm ci`.

For browser launch debugging, Playwright documents the DEBUG=pw:browser environment variable. For example:

DEBUG=pw:browser npx playwright test

7. Choose manual setup or a preconfigured image

Manual installation gives you control over the project, package versions, browser engines, and system setup. A preconfigured marketplace image may reduce initial setup work, but it introduces a vendor image and its listing terms into your deployment. AWS Marketplace includes vendor listings for Playwright environments; their presence does not establish a universal price, quality level, or compatibility guarantee. Check the current listing details for your region and account.

8. Performance, reliability, and cost

The sources do not establish a minimum memory requirement, an optimal EC2 instance size, a throughput figure, or a universal cost estimate for Playwright. These depend on the test suite, number of parallel workers, browser engines, page behavior, and how long the instances run. Begin with the needs of your own workload and monitor job duration, failures, and instance utilization before changing capacity or concurrency.

Keep versions aligned: Pin project dependencies through the lockfile and install matching browser binaries on the runner.
Separate setup from test execution: Install dependencies during provisioning or image creation where practical, rather than repeating downloads for each test invocation.
Use headless by default: It avoids the additional virtual-display setup required for headed Linux runs.
Evaluate capacity with your workload: No universal instance recommendation is supported here, so use observed behavior from your own suite.
Account for instance and marketplace terms: EC2 charges and any vendor image terms depend on the selected configuration and current account or region details. Check AWS and listing details for current pricing.

Or skip the browser setup

If your job is to capture website screenshots rather than run an interactive test suite, ScreenshotNeo is a website screenshot API and MCP server. A single request returns a PNG, JPEG, WebP, or PDF. See the ScreenshotNeo API documentation for options and parameters.

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

ScreenshotNeo accepts cookie and consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing, with response headers indicating the page verdict and billing status. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 screenshots.

FAQ

Does Playwright need a GUI on EC2?

No. Headless mode is the default and is suitable for ordinary server-side test runs. Use a virtual display such as Xvfb when you specifically need headed execution on Linux.

Should I install all three browser engines?

Only install the engines your project needs. The CLI supports installing a specific engine, and browser binaries must match the installed Playwright release.

Is there one recommended EC2 instance type for Playwright?

No universal instance size is established by the cited setup documentation. Select and evaluate capacity against your test workload.

Can I use a prebuilt Playwright AMI?

Vendor-preconfigured images are listed in AWS Marketplace. Verify the current image, vendor, region availability, and terms before using one.