The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →This guide assumes “custom browser image” means a Docker image containing Playwright and the browser binaries and system libraries it needs. You will pin the Playwright version, build and tag the image for a registry, push it, then verify the uploaded tag. If you mean a different browser automation framework, its package, browser installation, and operating-system dependency steps need separate validation.
What goes into a Playwright browser image?
A usable image needs three compatible parts: the Playwright runtime package used by your project, the browser binaries, and the operating-system libraries those browsers require. Playwright’s Docker examples install browsers and their dependencies on Node.js or Python base images. Its published browser image already contains browser binaries and system dependencies, but not the Playwright package, so your project must install that package separately. Playwright Docker documentation
Keep the Playwright package version and browser image or browser-install version aligned. A mismatch can prevent Playwright from finding its expected browser executables. Avoid floating versions for reproducible builds; select a real release and pin it consistently in the Dockerfile and project dependency manifest.
Choose a base image and version strategy
Build from a Node.js or Python base
Playwright documents examples based on node:20-bookworm and python:3.12-bookworm. These illustrate the dependency pattern, not a requirement to use those exact versions. Pick a supported runtime and OS combination that fits your application, then install a specific compatible Playwright release and its browsers with operating-system dependencies.
#1 Best Overall
Use Playwright’s published browser image
This can save you from installing browser binaries and system libraries yourself, but it does not include the Playwright package. Install the matching package in your project or image, and pin the published image to a specific release. The documentation lists Ubuntu 22.04 Jammy, Ubuntu 24.04 Noble, and Ubuntu 26.04 Resolute variants on its opened page. Firefox and WebKit browser builds target glibc; Alpine uses musl and is not supported for those builds. Check the current Playwright Docker guidance before choosing a base.
Write a Dockerfile with pinned versions
The examples below use 1.55.0 as a concrete version format; confirm that your selected release is compatible with your project and use the same version throughout. Do not leave a literal placeholder such as <VERSION> in a production Dockerfile.
Node.js example
This image installs Playwright and its browser builds plus system dependencies on the documented Node Bookworm base. The app files and startup command are project-specific.
FROM node:20-bookworm
WORKDIR /app
RUN npm install --save-exact [email protected]
RUN npx playwright install --with-deps
COPY . .
CMD ["node", "index.js"]For a real application, normally keep Playwright in your package manifest and lockfile, copy those files first, install from the lockfile, and then copy the remaining source. That improves repeatability and avoids reinstalling dependencies for every source change. Ensure the lockfile’s Playwright version matches the version used to install browsers.
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchPython example
FROM python:3.12-bookworm
WORKDIR /app
RUN pip install --no-cache-dir playwright==1.55.0
RUN playwright install --with-deps
COPY . .
CMD ["python", "main.py"]For a maintained application, record the pinned package version in your requirements or project file and install from that file. The browser install step must use the same environment and Playwright version that the application will run.
Build and test locally
- Save the Dockerfile in the project root and replace the example startup command with the entry point your app actually needs.
- Build a local image:
docker build -t browser-worker:1.55.0 . - Run a smoke test using your own application command. Confirm the process can launch the browser and complete a simple page load or test.
- If you will publish for multiple CPU architectures, build for each intended platform using Buildx rather than assuming your local machine’s architecture is the only target.
Set a registry name and tag
An image reference has this structure: [HOST[:PORT]/]NAMESPACE/REPOSITORY[:TAG]. The host can be Docker Hub’s default or another registry; namespace, repository, and tag identify where the image belongs and which release it represents. Prefer a meaningful immutable release tag, such as 1.55.0 or an application version, over relying only on a moving tag such as latest. Docker’s naming and push workflow is described in its repository push guide.
Build and upload the image
Buildx: build and push in one command
Authenticate to your target registry first if it requires credentials. Then run this from the directory containing the Dockerfile, replacing the example registry, namespace, repository, tag, and platform with your own:
docker buildx build
--platform linux/amd64
--tag registry.example.com/team/browser-worker:1.55.0
--push .--push sends the build result to the named registry. For multi-platform images, specify every intended platform, for example linux/amd64,linux/arm64, and push to a registry. Buildx also supports a registry exporter. Consult the Buildx build reference and exporters overview for available options.
Docker Hub: tag, then push
- Sign in when needed:
docker login. Docker manages registry credentials through this command. - Tag the local image for your Docker Hub namespace and repository:
docker tag browser-worker:1.55.0 NAMESPACE/browser-worker:1.55.0. - Upload it:
docker push NAMESPACE/browser-worker:1.55.0. - Open the repository’s Tags view and verify that the tag appears. Docker’s push command reference documents the command, and its push guide describes checking the repository.
Choose runtime permissions and browser flags
Image upload does not determine whether running the browser is safe. Playwright says its published Docker image is intended for testing and development, not visiting untrusted websites. It runs as root by default; Chromium’s sandbox is disabled when running as root. Root may be acceptable for trusted end-to-end tests, but for crawling or scraping untrusted sites Playwright recommends a separate user and a seccomp profile that enables the required user-namespace operations. Apply least privilege appropriate to your workload rather than adding broad permissions by default. Playwright’s Docker guidance
For Chromium, Playwright recommends --ipc=host because the default shared-memory setup can cause crashes. It also recommends --init to handle PID 1 and zombie-process issues. A typical local run might be:
docker run --rm --init --ipc=host
registry.example.com/team/browser-worker:1.55.0Use --cap-add=SYS_ADMIN only as a local-development troubleshooting step for unusual Chromium launch errors; it grants additional capability and should not be treated as a routine production fix.
Troubleshoot common build and push failures
- Playwright cannot find the browser executable: The package and installed browser versions may not match, or the project is using a different Playwright installation from the one that installed browsers. Pin and align versions, then rebuild.
- Browser launch reports missing libraries: Browser system dependencies were not installed for the chosen OS, or the base image is incompatible. Use the supported OS/runtime pattern and install dependencies with the Playwright browser install command.
- Firefox or WebKit fails on Alpine: The documented browser builds target glibc, not Alpine’s musl environment. Switch to a compatible glibc-based image.
- Chromium crashes or exits during a container run: Check shared memory and process initialization. Try the recommended
--ipc=hostand--init; reserve--cap-add=SYS_ADMINfor diagnosing unusual local launch errors. - Push is denied or authentication fails: Check that you are logged in to the intended registry and that the image reference uses a namespace/repository you may publish to. Run
docker loginfor the relevant registry, then push again. - The image is not visible under the expected tag: Confirm the complete host, namespace, repository, and tag in the image reference; then inspect the registry repository’s Tags view.
- A target machine cannot pull or run the image: Check the target CPU architecture against the platforms built into the image. Use Buildx with the required platform list and push the result to a registry.
Performance, reliability, and cost considerations
A custom image centralizes browser binaries and system dependencies, making deployment more repeatable when its versions are pinned. It also creates a maintenance responsibility: update the runtime, Playwright package, browsers, and OS base deliberately, rebuild, and validate the resulting image in your environment. Build cache and ordering affect how much work Docker repeats; copying dependency manifests before source files can avoid reinstalling packages for ordinary code edits.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Fix the driver behind crashes, sound loss and screen glitches3Clear out junk files and repair common Windows errorsRegistry upload cost, storage limits, retention policies, and bandwidth depend on the registry and account. The cited Docker documentation explains naming, build, and push operations but does not establish a universal price or quota, so check the terms for the registry you choose. For reliability, verify the pushed tag and test a pull and launch in an environment representative of deployment; a successful push alone does not prove the browser will launch under production permissions.
Or skip the browser setup
If your goal is simply to obtain website screenshots rather than run your own Playwright browser, ScreenshotNeo is a website screenshot API and MCP server for developers. A single GET request returns PNG, JPEG, WebP, or PDF. For example, this cURL request saves a WebP screenshot of Stripe:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for parameters and response details. It removes cookie/consent banners, newsletter popups, and chat widgets before capture; bot checks, blank pages, and failed loads are never billed; and its MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots per month with no card, and paid plans start at $5 for 3,000. Sign up for free and start with 1,000 screenshots a month, no card required.
Frequently Asked Questions
Can I use a floating Playwright version tag for the image?
A pinned release is safer: keep the package and browser image or install version aligned so Playwright can locate its browser executables.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Does Playwright’s published browser image include the Playwright package?
No. It contains browser binaries and system dependencies; the project still needs to install the Playwright package.
Can I publish one image for both AMD64 and ARM64?
Yes. Use Buildx with the intended platform list and push the multi-platform result to a registry.
Quick Recap
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.
