Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
To self-host headless Chrome, run Chrome inside a Docker container alongside the automation runtime your application already uses. Choose Puppeteer for a Node.js application that launches a local browser, Selenium Standalone Chrome for WebDriver clients that need a remote endpoint, or Playwright’s documented image for a Playwright workload. Pin compatible versions, plan shared memory and process cleanup, and decide explicitly how the browser sandbox will be maintained.
“Headless” no longer necessarily means a separate, stripped-down browser: since Chrome 112, Chrome’s regular implementation can run without displaying platform windows. The older, separate Headless implementation has been available as the chrome-headless-shell binary since Chrome 132.0.6793.0. Chrome’s Headless documentation explains the distinction.
Choose a container that matches your automation stack
Start with the library your code already uses. These images are not interchangeable in the sense of having the same client interface: Puppeteer launches Chrome through its own API, Selenium exposes a WebDriver service, and Playwright has its own browser runtime and remote-connection approach.
| Route | Best fit | Important deployment consideration |
|---|---|---|
| Puppeteer image | Node.js applications using Puppeteer to launch a browser. | Includes Chrome for Testing, dependencies, and a preinstalled Puppeteer version. The documented sandbox-mode command adds SYS_ADMIN. |
| Selenium Standalone Chrome | Selenium WebDriver clients or other compatible remote WebDriver clients. | Expose port 4444, allocate shared memory, and use a full tag to pin the browser and Grid version. |
| Playwright image | Applications already written against Playwright. | The documented image is intended for testing and development. For Chromium, Playwright recommends --ipc=host; remote client and container Playwright versions should match. |
For a single application that controls its own browser process, the Puppeteer or Playwright route keeps the browser close to the code. For clients that need to connect to a browser service over WebDriver, Selenium’s standalone image provides that service model. Compare the client interface, version coupling, deployment architecture, and sandbox policy before choosing.
#1 Best Overall
Run headless Chrome with Puppeteer
Puppeteer’s official image is hosted on GitHub Container Registry. It includes Chrome for Testing, the required dependencies, and a preinstalled Puppeteer version. Available tags include latest and version-specific tags; for repeatable deployments, choose a version-specific tag compatible with your application rather than relying on a moving tag. See the Puppeteer Docker guide for current image details.
From a shell where Docker is installed, run the documented command below, replacing the script path with a file available at that path in your working environment:
docker run -i --init --cap-add=SYS_ADMIN --rm
ghcr.io/puppeteer/puppeteer:latest
node -e "$(cat path/to/script.js)"The command uses --init to manage browser child processes and --cap-add=SYS_ADMIN, which the image documents for sandbox mode. The --rm option removes the stopped container. For stable use, replace latest with a suitable versioned tag and keep the image’s Puppeteer version compatible with the code you run.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
If you build your own image from a different base, use the Puppeteer project’s Dockerfile as a starting point for system dependencies. Avoid guessing at the libraries Chrome needs: missing dependencies can make the browser fail at launch even when the application itself installs successfully.
Run Chrome as a Selenium WebDriver service
Use Selenium Standalone Chrome when your client connects through WebDriver rather than launching a local browser process. This example follows the Selenium project’s reviewed documentation example and exposes WebDriver on port 4444:
docker run -d --rm
-p 4444:4444
--shm-size="2g"
selenium/standalone-chrome:4.48.0-20260905The 4.48.0-20260905 tag is the version shown in the project documentation reviewed for this article, not a promise that it remains the latest. Select a currently published full tag when deploying; Selenium recommends full tags to pin browser and Grid versions. Its documented --shm-size="2g" invocation is a project recommendation for browser containers, not a measured minimum or a guarantee that every workload needs exactly this amount. See the docker-selenium documentation for current tags and setup guidance.
Configure your Selenium client to connect to the Docker host’s port 4444. The project also documents an optional noVNC interface on port 7900 for visual debugging. Publish that debugging port only where it is appropriate for your environment; it is not needed for ordinary WebDriver requests.
Run a Playwright workload in Docker
Playwright documents its own Docker image and browser connection options. Its image is intended for testing and development. A typical Chromium run should include an init process and the IPC setting Playwright recommends:
docker run --init --ipc=host
mcr.microsoft.com/playwright:v1.63.0-noble
npx playwright testThe tag above reflects the example version in Playwright’s documentation, not a claim that it is the current release. Choose an image tag appropriate to your installed Playwright version. If you run Playwright Server in the container and connect from another machine, match the Playwright version in the client to the version in the container. The Playwright Docker guide describes the image and remote connection approaches.
Playwright recommends --ipc=host for Chromium because insufficient IPC/shared memory can lead Chromium to run out of memory and crash. Host IPC has deployment and isolation implications; use it only when it fits your environment’s container policy. Do not treat it as a universal Docker requirement for every browser image.
Keep the browser sandbox and container security explicit
Do not disable Chrome’s sandbox just to make a container launch more easily. Decide which user runs the browser, which capabilities the container receives, and whether pages may be untrusted.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minutePC 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 & 11- Puppeteer: the official image is designed to run Chrome in sandbox mode and documents adding
SYS_ADMINfor that setup. Apply the image’s documented security model rather than removing sandboxing as a convenience. - Playwright: the documentation says its default root-user configuration disables Chromium’s sandbox. For crawling or scraping untrusted sites, Playwright recommends a separate user and a seccomp profile that permits user namespaces; it does not recommend the image’s default configuration for visiting untrusted websites.
- Selenium or a custom image: review the selected image’s own user, privilege, and browser configuration. The guidance for one project’s image is not a universal Docker rule.
Keep browser containers isolated from credentials and networks they do not need, especially if the browser will load arbitrary URLs. Sandbox configuration, container privileges, network access, and the trustworthiness of pages are connected decisions, not independent toggles.
Plan versions, memory, and process cleanup
Pin compatible versions
Pin the container image and intentionally upgrade it. Puppeteer’s version-specific image tags map to Puppeteer versions; Selenium recommends a full image tag to fix browser and Grid versions. For Playwright remote connections, keep the client and container Playwright versions aligned. During upgrades, check that the browser, driver where applicable, automation library, image tag, and target CPU architecture work together.
Use an init process for browser children
Browser automation can create child processes. Puppeteer and Playwright recommend an init process in their documented Docker usage. In Docker commands, --init provides that process; use a suitable custom entrypoint if your deployment design handles it another way. This helps manage child processes when the browser or container exits.
Size shared memory for the actual workload
Selenium’s example uses --shm-size="2g"; Playwright recommends --ipc=host with Chromium. These are distinct project recommendations, not interchangeable universal settings or performance guarantees. Browser-heavy pages, parallel workers, and the selected runtime affect resource needs, so monitor the container under representative work and adjust its memory and IPC configuration within your host’s policy.
Free tools Windows power users keep installed
One-click scans. No signup required.
Troubleshoot common startup and runtime failures
Chrome exits immediately or reports missing libraries
A custom base image may lack system dependencies required by Chrome. Start from the matching project image or use its Dockerfile as a dependency reference. Also confirm that the image architecture and browser build are compatible with the host and application.
The browser will not launch in sandbox mode
Check the selected image’s documented user and capability requirements before changing sandbox settings. For Puppeteer’s official image, the sandbox-mode invocation documents --cap-add=SYS_ADMIN. Do not solve a launch error by casually disabling the sandbox, particularly when loading untrusted pages.
Chromium crashes or runs out of memory
Review container memory and shared-memory/IPC configuration. Selenium documents a 2 GB shared-memory setting for its browser container; Playwright recommends host IPC for Chromium. Treat these as starting points from the respective projects, not as guarantees. Reduce concurrency or adjust resource allocation if the workload exceeds the container’s available resources.
Child processes remain after a job ends
Run the container with --init or use an entrypoint that performs equivalent process management, as the Puppeteer and Playwright guides recommend. Also ensure your application closes browser contexts and browser processes when its job finishes.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →Remote WebDriver or Playwright clients cannot connect
For Selenium, verify that the container is running and host port 4444 is mapped to the service. For Playwright Server, follow the documented server/client connection pattern and confirm that the client and container versions match. Check host firewall and network routing separately from browser startup.
A version upgrade breaks previously working automation
Verify the complete compatibility set: image tag, Chrome or Chromium build, driver if used, automation package, and architecture. Replace floating tags with deliberate version pins and test updates before deploying them broadly.
Or skip the browser setup
If your goal is to get screenshots rather than operate a browser fleet, ScreenshotNeo offers a one-request screenshot API. For example, this cURL request saves a WebP shot of Stripe; see the ScreenshotNeo API documentation for request options.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpScreenshotNeo removes cookie/consent banners, newsletter popups, and chat widgets before capture; those cleanup steps can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and response headers indicate 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 shots per month with no card; paid plans start at $5 for 3,000 shots.
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Repair Windows errors before they cause bigger problems3Scan for outdated or missing drivers - takes under a minuteSign up free for ScreenshotNeo: 1,000 screenshots a month, no card required.
Frequently Asked Questions
How do I create a Docker container that runs Headless Chrome?
Use the official Docker image for your automation stack: Puppeteer for a Puppeteer-launched browser, Selenium Standalone Chrome for a WebDriver service, or Playwright’s image for Playwright. Pin a compatible image version and configure the browser’s process, memory, and sandbox requirements.
Is Chrome Headless the same as the old Headless Shell?
Chrome’s unified Headless mode uses Chrome without displaying platform windows. Since Chrome 132.0.6793.0, the legacy Headless implementation is available separately as the chrome-headless-shell binary.
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.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →
