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
ToggleThis 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.

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 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.
