Playwright Masters

Playwright Docker: The Complete Guide (2026)

Playwright Docker means running Playwright browser tests inside a Docker container, usually built from Microsoft’s official image mcr.microsoft.com/playwright. The image already holds Chromium, Firefox, WebKit and every Linux library they need. You add your test code, run one command, and get the same result on every laptop, CI server and cloud machine.

Think of Docker as a lunch box. Your tests, the browsers and all their helpers go inside the box. Wherever you carry the box, the lunch tastes the same. That is why teams stop hearing the famous line, “but it works on my machine.”

Table of Contents

This guide is written by the team at Playwright Masters, and it is part of our free Playwright learning series. It covers official image tags, ready-to-copy Dockerfiles for Node.js, TypeScript, Python and Java, Docker Compose, CI/CD, remote browser servers, sharding, Kubernetes, security and a full troubleshooting table.

What you will learn in 2 minutes of scrolling:

  • The one image tag rule that prevents the most common Playwright Docker error.
  • The three Docker flags (–ipc=host, –init, –user pwuser) that stop crashes, zombie processes and security risks.
  • How to copy HTML reports and traces out of a container.
  • How to split 800 tests across 4 containers and merge one clean report.
  • When to use Docker, a local install, or a cloud browser grid.

             New to the tool itself? Read What is Playwright? first, then come back here.

Playwright Docker

What Is Playwright Docker?

Playwright Docker is the practice of packaging Playwright, its browsers and its system libraries into a Docker container so tests run in an identical Linux environment everywhere. Microsoft publishes official images for Node.js, Python, Java and .NET, so you rarely need to install browsers by hand.

Playwright is a free, open-source browser automation framework from Microsoft. Docker is a tool that packs software and everything it needs into a sealed box called a container. Put them together and your browser tests become portable.

Key terms in plain words

Term

Simple meaning

Example in Playwright

Image

A frozen recipe for a computer

mcr.microsoft.com/playwright:v1.64.1-noble

Container

A running copy of an image

The box where npx playwright test runs

Dockerfile

A text file with build steps

FROM, COPY, RUN, CMD lines

Tag

The version label on an image

v1.64.1-noble

Volume

A shared folder between your PC and the container

Saves playwright-report/ to your disk

Registry

An online shelf that stores images

Microsoft Container Registry (MCR)

Noble / Jammy

Ubuntu 24.04 / Ubuntu 22.04 base systems

Pick one and keep it fixed

If you want to understand how Playwright talks to browsers under the hood, see our guide on Playwright architecture. It explains why browsers need so many system libraries in the first place.

Why Run Playwright Tests in Docker?

Teams run Playwright in Docker to get one identical test environment for every developer and every pipeline. This removes browser version drift, missing Linux libraries and font differences, which are the top causes of tests that pass locally and fail in CI.

  • Same result everywhere. The browser build, fonts and libraries are locked inside the image.
  • Zero browser setup. No npx playwright install –with-deps on each new machine.
  • Faster onboarding. A new tester runs one docker run command on day one.
  • Cleaner CI. Every job starts from a fresh, clean box, so old files never leak into new runs.
  • Stable screenshots. Pixel-based checks stop failing because of a different font on a teammate’s laptop.
  • Easy scaling. Start 4, 10 or 50 identical containers to finish a big suite faster.
  • Safe experiments. Try a new Playwright version in a container without touching your main setup.

When Docker is not needed: If you are learning alone on one laptop and write a few tests, a normal local install is simpler. Follow our Playwright installation guide for that path, and switch to Docker when a team or a pipeline joins in.

Official Playwright Docker Images and Tags (2026)

The official Playwright images live on Microsoft Container Registry under mcr.microsoft.com/playwright, with separate paths for Python, Java and .NET. As of November 2026 the current release on the official Playwright Docker docs is v1.64.1, offered on Ubuntu 24.04 (noble), Ubuntu 22.04 (jammy) and Ubuntu 26.04 (resolute).

Language

Image path

Example pinned tag

Node.js / TypeScript

mcr.microsoft.com/playwright

:v1.64.1-noble

Python

mcr.microsoft.com/playwright/python

:v1.64.1-noble

Java

mcr.microsoft.com/playwright/java

:v1.64.1-noble

.NET

mcr.microsoft.com/playwright/dotnet

:v1.64.1-noble

The golden rule of tags

The Playwright version in your image tag must match the Playwright version in your project. If your package.json says 1.64.1, your image must say v1.64.1. A mismatch gives the classic error “Executable doesn’t exist”, because the library looks for a browser build that is not in the box.

  • Always pin a version. Avoid latest; it silently changes under you.
  • Pin the OS too. -noble today, a planned move to a newer base later.
  • Upgrade together. Bump the npm, pip or Maven version and the image tag in the same commit.
  • Skip Alpine. Alpine and other musl-based Linux systems are not supported for Playwright browsers.

The images contain browsers and system libraries. Your own test project and its Playwright package are installed on top, usually with npm ci, pip install or Maven.

How to Run Playwright Tests in Docker: Step by Step (Node.js and TypeScript)

To run Playwright tests in Docker, start from the official image, copy your project in, install dependencies with npm ci, and run npx playwright test with the –ipc=host and –init flags. The full setup takes about 10 minutes and five small files.

Step 1: Check your Playwright version

Open package.json and find @playwright/test. Note the exact number, for example 1.64.1. Your image tag will use this same number.

npx playwright –version

Step 2: Write the Dockerfile

Create a file named Dockerfile in your project root.

# Browsers + Linux libraries are already inside

FROM mcr.microsoft.com/playwright:v1.64.1-noble

 

WORKDIR /app

 

# Copy only dependency files first (faster rebuilds)

COPY package.json package-lock.json ./

RUN npm ci

 

# Now copy the tests and config

COPY . .

 

CMD [“npx”, “playwright”, “test”]

Copying package.json before the rest of the code is a speed trick. Docker caches the npm ci layer, so it only reinstalls packages when your dependencies change, not every time you edit a test.

Step 3: Add a .dockerignore file

This keeps heavy or private files out of the image.

node_modules

playwright-report

test-results

blob-report

.git

.env

Step 4: Make the config container-friendly

In playwright.config.ts, stop the HTML report from trying to open a browser window, and keep traces for failed tests.

import { defineConfig } from ‘@playwright/test’;

 

export default defineConfig({

  testDir: ‘./tests’,

  retries: process.env.CI ? 2 : 0,

  reporter: [[‘html’, { open: ‘never’ }]],

  use: {

    baseURL: process.env.BASE_URL ?? ‘http://localhost:3000’,

    trace: ‘on-first-retry’,

    screenshot: ‘only-on-failure’,

  },

});

New to config files? Our Playwright with TypeScript guide walks through every option.

Step 5: Build the image

docker build -t my-playwright-tests .

Step 6: Run the tests and save the report

docker run –rm –init –ipc=host \

  -v “$(pwd)/playwright-report:/app/playwright-report” \

  -v “$(pwd)/test-results:/app/test-results” \

  -e BASE_URL=https://staging.example.com \

  my-playwright-tests

What each flag does:

  • –rm deletes the container when tests finish, so no clutter piles up.
  • –init adds a tiny process manager that cleans up leftover browser processes (zombies).
  • –ipc=host gives Chromium enough shared memory so it does not crash on big pages.
  • -v links a folder on your computer to a folder in the container, so reports survive.
  • -e passes settings like the site address into your tests.

Step 7: Open the report on your computer

npx playwright show-report playwright-report

The report and traces now sit on your own disk. Learn to read them in our Playwright HTML report and Playwright Trace Viewer guides.

Testing an app running on your own computer

Inside a container, localhost means the container itself, not your laptop. To reach an app on your machine, add –add-host=hostmachine:host-gateway to docker run and use http://hostmachine:3000 as the base URL. On Docker Desktop for Windows and Mac, host.docker.internal also works.

Playwright Docker for Python and Java

Python and Java teams use the same idea: pick an image whose Playwright version matches the project, install dependencies, then run the test command. Only the package manager and the test runner change.

Playwright Python in Docker (pytest)

The quickest option is the official Python image for a one-off run:

docker run -it –rm –ipc=host \

  mcr.microsoft.com/playwright/python:v1.64.1-noble /bin/bash

For a repeatable project image, many Python teams start from a slim Python base and let Playwright install only the browser they need. This keeps the image smaller.

FROM python:3.12-bookworm

 

WORKDIR /app

COPY requirements.txt .

# requirements.txt pins: playwright==1.64.1 and pytest-playwright

RUN pip install –no-cache-dir -r requirements.txt \

 && playwright install –with-deps chromium

 

COPY . .

CMD [“pytest”, “–browser”, “chromium”, “–tracing”, “retain-on-failure”]

Installing only Chromium can save hundreds of megabytes compared with all three browsers. Add firefox or webkit to the install line when your test plan needs them. For syntax and fixtures, see Playwright with Python.

Playwright Java in Docker (Maven)

The Java image comes with Java and Maven ready, so the Dockerfile stays short.

FROM mcr.microsoft.com/playwright/java:v1.64.1-noble

 

WORKDIR /app

COPY pom.xml .

# Download dependencies once, cache the layer

RUN mvn -B -q dependency:go-offline

 

COPY src ./src

CMD [“mvn”, “-B”, “test”]

Keep the com.microsoft.playwright version in pom.xml equal to the image tag. Then run it with the same flags as before:

docker build -t pw-java .

docker run –rm –init –ipc=host pw-java

Java users who are new to the API can start with Playwright with Java.

Playwright with Docker Compose: App and Tests Together

Docker Compose lets you start your web app and your Playwright tests with one command, docker compose up. The tests wait until the app is healthy, run against it on a private network, then exit with a pass or fail code.

# docker-compose.yml

services:

  web:

    build: ./app

    ports:

      – “3000:3000”

    healthcheck:

      test: [“CMD”, “curl”, “-f”, “http://localhost:3000”]

      interval: 5s

      retries: 10

 

  e2e:

    build: .

    init: true

    ipc: host

    depends_on:

      web:

        condition: service_healthy

    environment:

      – BASE_URL=http://web:3000

    volumes:

      – ./playwright-report:/app/playwright-report

Run it and stop everything when tests finish:

docker compose up –build –abort-on-container-exit –exit-code-from e2e

Notice the base URL is http://web:3000. Inside Compose, each service can reach the others by its service name, like calling a classmate by name instead of by seat number. The –exit-code-from e2e flag makes the whole command fail when a test fails, which is exactly what a pipeline needs.

Playwright Docker in CI/CD Pipelines

In CI/CD, the simplest pattern is to run the whole job inside the official Playwright image. The pipeline then skips browser downloads, which often saves one to three minutes per run, and every job starts from the same clean environment.

GitHub Actions

name: e2e

on: [push, pull_request]

jobs:

  playwright:

    runs-on: ubuntu-latest

    container:

      image: mcr.microsoft.com/playwright:v1.64.1-noble

      options: –user 1001 –ipc=host

    steps:

      – uses: actions/checkout@v4

      – run: npm ci

      – run: npx playwright test

      – uses: actions/upload-artifact@v4

        if: always()

        with:

          name: playwright-report

          path: playwright-report/

          retention-days: 14

GitLab CI

e2e:

  image: mcr.microsoft.com/playwright:v1.64.1-noble

  script:

    – npm ci

    – npx playwright test

  artifacts:

    when: always

    paths:

      – playwright-report/

    expire_in: 1 week

Jenkins (declarative pipeline)

pipeline {

  agent {

    docker {

      image ‘mcr.microsoft.com/playwright:v1.64.1-noble’

      args ‘–ipc=host –init’

    }

  }

  stages {

    stage(‘e2e’) {

      steps {

        sh ‘npm ci’

        sh ‘npx playwright test’

      }

    }

  }

  post {

    always { archiveArtifacts artifacts: ‘playwright-report/**’, allowEmptyArchive: true }

  }

}

The if: always(), when: always and post { always } lines upload the report even when tests fail. That is the run you most need to inspect. For full pipeline design, including triggers, secrets and gating deploys, read our Playwright CI/CD guide.

Remote Mode: Run Only the Browsers in Docker

Remote mode keeps your tests on your own machine and moves only the browsers into a Docker container. Playwright starts a browser server inside the container, and your tests connect to it over a WebSocket address such as ws://127.0.0.1:3000/.

This is handy on Windows or macOS when you want Linux browsers for stable screenshots, but still want to edit and run tests from your normal editor.

Start the browser server:

docker run -p 3000:3000 –rm –init -it –workdir /home/pwuser –user pwuser \

  mcr.microsoft.com/playwright:v1.64.1-noble \

  /bin/sh -c “npx -y playwright@1.64.1 run-server –port 3000 –host 0.0.0.0”

Connect from a Node.js test config:

export default defineConfig({

  use: {

    connectOptions: { wsEndpoint: ‘ws://127.0.0.1:3000/’ },

  },

});

Connect from Python:

from playwright.sync_api import sync_playwright

 

with sync_playwright() as p:

    browser = p.chromium.connect(“ws://127.0.0.1:3000/”)

    page = browser.new_page()

    page.goto(“https://playwrightmasters.in/”)

    print(page.title())

    browser.close()

Two rules keep remote mode happy. First, the client and server Playwright versions must match exactly. Second, if your app runs on your machine, start the container with –add-host=hostmachine:host-gateway and point tests at hostmachine instead of localhost.

The same “browser as a service” idea powers AI agents that drive browsers. Our Playwright MCP guide shows how AI assistants control Playwright, and many teams host that server in a container too.

Scaling Playwright Docker: Sharding, Parallel Containers and Kubernetes

To make a large suite finish faster, split it into shards and run each shard in its own container at the same time. Playwright’s –shard=1/4 flag gives each container a quarter of the tests, and merge-reports joins the pieces into one HTML report.

There are two levels of speed. Workers run tests in parallel inside one container. Shards spread tests across many containers or machines. Use both for big suites. Our Playwright parallel testing guide explains workers in depth.

Sharding in GitHub Actions with a matrix

jobs:

  test:

    runs-on: ubuntu-latest

    container:

      image: mcr.microsoft.com/playwright:v1.64.1-noble

      options: –user 1001 –ipc=host

    strategy:

      fail-fast: false

      matrix:

        shard: [1, 2, 3, 4]

    steps:

      – uses: actions/checkout@v4

      – run: npm ci

      – run: npx playwright test –shard=${{ matrix.shard }}/4 –reporter=blob

      – uses: actions/upload-artifact@v4

        if: always()

        with:

          name: blob-report-${{ matrix.shard }}

          path: blob-report

A final job downloads all blob-report-* artifacts into one folder and runs:

npx playwright merge-reports –reporter html ./all-blob-reports

Rough time saved

Setup

800 tests at ~3 s each, 4 workers

Approx. wall time

1 container

800 × 3 s ÷ 4 workers

~10 min

4 shards

each shard does 200 tests

~2.5 min + setup

8 shards

each shard does 100 tests

~1.3 min + setup

Real numbers depend on your app’s speed and on container start time, so measure your own suite.

Kubernetes tips

Kubernetes pods cannot use –ipc=host, so give Chromium shared memory by mounting a memory-backed volume at /dev/shm.

spec:

  containers:

    – name: e2e

      image: registry.example.com/my-playwright-tests:1.64.1

      resources:

        requests: { cpu: “2”, memory: “4Gi” }

        limits:   { cpu: “2”, memory: “4Gi” }

      volumeMounts:

        – name: dshm

          mountPath: /dev/shm

  volumes:

    – name: dshm

      emptyDir:

        medium: Memory

        sizeLimit: 1Gi

  • Give each pod about 1 CPU and 1 to 2 GB of memory per Playwright worker.
  • Set workers in the config to match the pod’s CPU limit, not the node’s.
  • Use an Indexed Job and pass the pod index into –shard to split work across pods.
  • In plain Docker, –shm-size=1gb is the alternative when –ipc=host is not allowed.

Docker Makes Visual Testing Reliable

Visual tests compare screenshots pixel by pixel, so baselines must be created in the same pinned Docker image that CI uses. Otherwise, small font and rendering differences fail tests even when nothing is broken.

One detail many testers miss: Playwright adds the operating system to every snapshot file name, such as home-chromium-linux.png or home-chromium-darwin.png. A baseline made on a Mac is saved under a different name, so a Linux CI run cannot find it at all. Generate and commit the -linux files from inside the container, and every run compares like with like.

For the exact container command, thresholds and masking, follow our Playwright visual testing guide.

Playwright Docker Best Practices and Security Checklist

The best Playwright Docker setups pin versions, keep images small, run as a non-root user for untrusted sites, and always export reports. Follow this checklist before you call your setup production-ready.

  • Image tag pinned to the exact Playwright version, for example v1.64.1-noble.
  • package-lock.json, requirements.txt or pom.xml pins the same version.
  • –init and –ipc=host (or –shm-size=1gb) on every docker run.
  • .dockerignore excludes node_modules, reports, .git and .env files.
  • Dependency files copied before source code to reuse cached layers.
  • Secrets passed at run time with -e or CI secrets, never baked into the image.
  • Reports, traces and screenshots saved through volumes or CI artifacts.
  • Workers set to match the CPU you give the container.
  • One upgrade commit bumps the library and the image tag together.
  • Custom images built for both amd64 and arm64 with docker buildx if your team uses Apple Silicon laptops.

Security: trusted tests vs untrusted sites

The official images run as root by default and are designed for testing your own apps. Root is fine for end-to-end tests on sites you trust. If you crawl or scrape sites you do not control, Microsoft recommends a stricter run:

docker run -it –rm –ipc=host –user pwuser \

  –security-opt seccomp=seccomp_profile.json \

  mcr.microsoft.com/playwright:v1.64.1-noble /bin/bash

The pwuser account is a normal user already created in the image. The seccomp profile lets Chromium’s own sandbox work safely as that user. Never run unknown websites as root inside a container that shares secrets or networks with production systems.

These habits also make tests calmer. Many “random” failures are really environment problems, and our Playwright flaky tests guide shows how to separate the two.

Playwright Docker Troubleshooting: Errors and Fixes

Most Playwright Docker problems come from five causes: a version mismatch, low shared memory, missing process cleanup, wrong network address, or files not leaving the container. Find your symptom below and apply the fix.

Symptom or error

Likely cause

Fix

Executable doesn’t exist at /ms-playwright/…

Image tag and project version differ

Make the image tag equal the installed Playwright version

Chromium crashes, “Target page, context or browser has been closed”

Docker’s default 64 MB shared memory is too small

Add –ipc=host or –shm-size=1gb; in Kubernetes mount /dev/shm

Container never exits, leftover browser processes

No init process to reap zombies

Add –init (or init: true in Compose)

net::ERR_CONNECTION_REFUSED on localhost

localhost points to the container, not your PC

Use –add-host=hostmachine:host-gateway and http://hostmachine:PORT

No report after the run

Files stayed inside the deleted container

Mount playwright-report with -v, or upload as a CI artifact

Screenshot tests fail only in CI

Baselines made on another OS

Regenerate baselines inside the same image

Permission denied writing to a mounted folder

Container user differs from your host user

Run with –user (id-u):(id -g) or fix folder ownership

Firefox fails to start in GitHub Actions as root

HOME folder owned by another user

Use options: –user 1001, or set HOME: /root in the job env

exec format error

Image built for a different CPU type

Use the official multi-arch image or build with docker buildx –platform

Very slow image builds

Source copied before npm ci breaks caching

Copy dependency files first, then the rest

Still stuck? Run the failing test with tracing on, copy the trace out, and open it locally. Our Playwright debugging guide shows step-by-step methods that work the same inside and outside Docker.

Docker vs Local Install vs Cloud Browser Grid

Choose Docker when you want the same environment for a team and a pipeline at low cost. Choose a local install for solo learning, and a cloud grid when you need real Windows, macOS or mobile browsers that Linux containers cannot provide.

Factor

Local install

Playwright in Docker

Cloud browser grid

Setup time

~5 min

~10 min once, then 1 command

Account + config

Same result on every machine

No

Yes

Yes

Cost

Free

Free (your hardware)

Paid per minute or seat

Real macOS / Windows browsers

Only your own OS

Linux only

Yes

Scales to many parallel runs

Limited by one PC

Yes, with more containers

Yes

Works offline

Yes

Yes, after first pull

No

Best for

Beginners, quick scripts

Teams, CI/CD, visual tests

Cross-OS coverage at large scale

Many mature teams use all three: local runs while writing a test, Docker in every pull request, and a cloud grid nightly for extra OS coverage. If you are comparing tools before choosing Playwright at all, see Playwright vs Selenium and Playwright vs Cypress.

Your Playwright Learning Path: Where Docker Fits

Learn Docker after you can write, organise and debug Playwright tests. A container only packages your suite; it cannot fix a messy one. Build a clean Playwright framework with the Page Object Model first, then put it in a container.

Docker, sharding and CI/CD questions come up often in automation interviews. Practise explaining image tags, –ipc=host and sharding in your own words, and review our Playwright interview questions before your next round. For the full order of topics from beginner to advanced, follow the Playwright roadmap.

FAQs

Is there an official Playwright Docker image?

Yes. Microsoft publishes official Playwright images on Microsoft Container Registry at mcr.microsoft.com/playwright, with separate images for Python, Java and .NET. Each image includes Chromium, Firefox, WebKit and their Linux dependencies.

Which Playwright Docker image tag should I use?

Use the tag that matches your project’s Playwright version and a fixed Ubuntu base, for example v1.64.1-noble. Avoid latest, because it can change without warning and break your tests.

Why do I get “Executable doesn’t exist” in Docker?

This error means the Playwright library in your project expects a different browser build than the one inside the image. Make the image tag and your installed Playwright version identical, then rebuild.

Why is –ipc=host recommended for Playwright in Docker?

Chromium uses shared memory, and Docker gives containers only 64 MB by default. –ipc=host lets Chromium use the host’s shared memory so it does not run out and crash. –shm-size=1gb is a safe alternative.

Can I run Playwright in an Alpine Docker image?

No. Playwright browsers are not supported on Alpine or other musl-based Linux systems. Use the official Ubuntu-based images or a Debian-based image such as python:3.12-bookworm.

Does Playwright Docker work on Apple Silicon (M1, M2, M3, M4) Macs?

Yes. The official images support both amd64 and arm64, so Docker pulls the right one for your Mac. If you build custom images for a mixed team, build both types with docker buildx.

Can I run headed (visible) browsers in Docker?

Containers have no screen, so tests run headless by default. For visual debugging, record traces and open them locally, or use remote mode so the browsers run in Docker while you watch from your own machine.

How big is the Playwright Docker image?

The official image with all three browsers is large, often more than 1 GB to download. To shrink a custom image, install only the browsers you test, for example Chromium alone.

How do I get the HTML report out of a Docker container?

Mount a folder with -v “$(pwd)/playwright-report:/app/playwright-report” when you run the container, or upload the folder as a CI artifact. The report then stays on your machine after the container is deleted.

Is the Playwright Docker image safe for web scraping?

The default image is built for testing your own apps and runs as root. For untrusted sites, run as the built-in pwuser account with Microsoft’s seccomp profile so the Chromium sandbox can protect the system.

Should beginners learn Playwright with Docker?

Beginners should first learn Playwright with a normal local install, then add Docker once they write real suites or join a team. Docker becomes essential when tests move into CI/CD pipelines.

Conclusion: Ship Tests That Behave the Same Everywhere

Playwright Docker gives your tests one sealed, repeatable home: the official image for browsers, a pinned version tag, three safety flags and reports that leave the container. Start with the seven-step Node.js setup above, move it into CI, then add sharding when your suite grows.

If you want guided, hands-on practice with Docker, CI/CD and real project frameworks, explore the training at Playwright Masters. You can check the Playwright course fee in Hyderabad, and teams can ask about Playwright corporate training. Browse every free guide on our Playwright blog.

Playwright Masters automation testing logo - White Back ground

Playwright Masters Team

Playwright Automation Testing Experts | Industry-Focused Training & Practical Learning

Playwright Masters is a dedicated automation testing training platform focused on helping learners build practical skills in Playwright automation testing. Our training covers real-world automation concepts, framework practices, coding, debugging, API testing, cross-browser testing, CI/CD, and interview preparation to help learners develop job-ready testing skills.

Scroll to Top

Start Your Playwright Automation Career Today

Get FREE Demo + Syllabus & Become Job-Ready in Playwright.