Playwright Docker: Run Browsers in Containers

Browser automation that works on a developer's laptop often fails on a server. Missing system libraries, different fonts, too little shared memory and processes that never exit are common causes. Containers solve much of this by packaging the browsers and their dependencies in a known image. A Playwright Docker setup gives every run the same environment, whether it is a nightly crawl, a scheduled report download or a test suite in CI. There are a few details to get right, though, and the official documentation is clear that the standard image is not meant for every job. This guide covers the image, the recommended flags, users and security, resources and how to run many browser jobs without surprises.

What the official Playwright image contains

Microsoft publishes a Playwright image to its container registry. According to the Playwright documentation, the image includes the Playwright browsers and the system dependencies those browsers need, but the Playwright package itself is not included and must be installed separately in your own image (Playwright: Docker). Tags include the Playwright version and the base operating system, so you can pin an exact version rather than pulling whatever is newest.

Pinning matters. The documentation notes that when tests run remotely, the Playwright version in your code should match the version running in the container. In practice, keep the image tag and the Playwright package version in your requirements file in step, and update them together.

Know what the image is for

The documentation states that the image is intended for testing and development purposes, and that it is not recommended to use it to visit untrusted websites. That distinction is important for scraping and crawling, where scripts visit pages you do not control.

By default the container runs browsers as the root user, which disables the Chromium sandbox because the sandbox is not available with root. The documentation says root may be acceptable for trusted code such as end-to-end tests of your own site, but for web scraping or crawling it recommends creating a separate user inside the container and using the seccomp profile it provides. If your jobs visit third-party sites, build your own image on top of the official one, add a non-root user and follow the documented security settings. For a wider view of running many browser workers at once, see our guide to headless browser scraping.

Use the recommended Playwright Docker flags

The Playwright documentation recommends two run options:

• Use the init flag so a small init process runs as PID 1. Without it, processes with PID 1 get special treatment, which the documentation names as a common reason for zombie processes.
• Use the host IPC option when running Chromium. The documentation warns that without it, Chromium can run out of memory and crash.

If your platform does not allow host IPC, for example on some managed container services, look for an equivalent way to give the container enough shared memory and test carefully under realistic load.

Keep the scripts themselves robust

A container fixes the environment, not the script. Stable locators, sensible waits, timeouts on every navigation and clear handling of missing elements still decide whether a job succeeds. Our guide to Playwright web scraping covers these script-level habits, which apply inside and outside containers alike. Test scripts locally in the same image before deploying, so differences between your laptop and the server show up early.

Build a small, predictable image

A typical Dockerfile for a Playwright job:

• Starts from a pinned Playwright image tag
• Installs the Playwright package at the same version, plus your other dependencies from a pinned requirements file
• Copies only the code the job needs
• Creates and switches to a non-root user for crawling work
• Sets a clear entry command that runs one job and exits

Keep secrets out of the image. Pass credentials at runtime through environment variables or a secrets manager, never through build arguments or files copied into layers, because image layers can be inspected by anyone with access to the image.

Size memory and concurrency with care

Browsers use a lot of memory, and each open page adds more. Rather than guessing, measure: run your job with realistic pages and watch memory and CPU in the container. Then set limits based on what you observed, with headroom. Practical habits:

• Close pages and contexts as soon as each task finishes
• Limit how many pages run at once in a single container
• Prefer several smaller containers over one large one, so a crash affects fewer tasks
• Restart workers periodically for long-running jobs to clear any slow memory growth
• Block heavy resources such as video when the job does not need them

Worked example: a hypothetical container plan

The table below is a hypothetical plan for two browser jobs run by the same team. It shows the decisions involved, not tested settings.

DecisionNightly test suitePublic catalogue crawlSites visitedOwn staging site (trusted)Third-party sites (untrusted)Base imagePinned Playwright tagPinned Playwright tagUserRoot acceptable per docsSeparate non-root user and seccomp profileInit flagYesYesHost IPC or more shared memoryYesYesPages per containerSet by measured memorySet by measured memory and site rate limitsSecretsTest account from CI secretsNone neededOn failureSave trace and screenshotLog URL, retry later with backoff

Debug failures inside containers

When a job fails only in the container, collect evidence rather than guessing. Save screenshots, logs and Playwright traces from failed runs to a mounted volume or object storage. Check that fonts and locale settings match what the target pages expect, because missing fonts can change layout and break text-based checks. Run the same image locally with the same flags to reproduce the problem.

Run containers on a schedule or a queue

For scheduled work, a cron job or a scheduled task in your container platform can start a container, run the job and stop. For larger workloads, put tasks on a queue and run a pool of worker containers that each take one task at a time. Either way, record each run's outcome, duration and errors, and alert on repeated failures. Respect the sites you visit: keep request rates modest and follow each site's rules, however many containers you can afford to run.

Frequently Asked Questions

Does the Playwright Docker image include Playwright itself?

No. According to the documentation, it includes the browsers and their system dependencies, and the Playwright package must be installed separately at a matching version.

Is the official image safe for web scraping?

The documentation says the image is intended for testing and development and is not recommended for visiting untrusted websites. For scraping or crawling, it recommends a separate user and the seccomp profile.

Why does Chromium crash in my container?

One documented cause is shared memory. The documentation recommends the host IPC option when running Chromium, because without it Chromium can run out of memory.

Should I pin the image version?

Yes. Pin the image tag and keep it in step with the Playwright package version in your code, then update both together.

Run browser jobs reliably

We design container setups for browser automation, from image and security settings to scheduling and monitoring. See our B2B lead mining and prospect verification service, or talk to us about Playwright Docker setups.

About the Author

Manav Sharma is the founder of Insyrge and a CRM solutions architect. He works across Zoho, Salesforce, HubSpot, Odoo and more, designing the CRM setups, integrations and automations that keep sales and operations teams working from the same data.