Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
Install Chrome Headless Shell with Chrome for Testing’s @puppeteer/browsers command-line utility: run npx @puppeteer/browsers install chrome-headless-shell@stable for the latest available Stable-channel build, or replace stable with an exact version to pin a release. First check Chrome for Testing’s availability dashboard for your target operating system and CPU architecture; the official documentation does not establish a complete current platform matrix.
Choose Headless Shell or modern Chrome Headless first
“Headless Chrome” can refer to two different things. Modern unified Headless mode runs the regular Chrome browser without showing its windows. Chrome Headless Shell is a separate, standalone binary descended from Chrome’s former, separate Headless implementation. The choice affects which binary you download and, if you use Puppeteer, which headless mode you select.
When Headless Shell fits
Chrome for Developers describes the shell as a lighter wrapper with fewer dependencies, including no X11/Wayland or D-Bus requirement. It can suit screenshot automation and web scraping when those characteristics match the environment and task. That description is not a measured promise that it will be faster for every site, machine, or workload.
Free tools Windows power users keep installed
One-click scans. No signup required.
When unified Headless fits
Choose unified Headless when your tests need the more authentic, feature-rich behavior of the regular Chrome browser—for example, high-fidelity end-to-end app testing or browser-extension testing. Chrome’s documentation identifies unified Headless as the better fit for those cases. This is a workload distinction, not a claim that every feature or test behaves identically across all versions.
#1 Best Overall
The version history helps clarify why both choices still appear in documentation. Unified Headless has been part of Chrome since version 112. The former separate implementation became available as the standalone chrome-headless-shell binary beginning with Chrome 120. Since Chrome 132.0.6793.0, that older Headless mode is available only as the standalone binary. Chrome for Developers’ “Chrome Headless mode” page, last updated 2024-10-21 UTC, documents the distinction.
Check that your target build is available
Before downloading, identify the release channel, version, operating system, and CPU architecture your automation environment needs. Use Chrome for Testing’s availability dashboard to confirm that the desired artifact exists for that combination. Chrome for Testing lists version information for Stable, Beta, Dev, and Canary; its JSON API endpoints expose the latest version for each channel, which can be useful when a script needs to look up a channel’s current build.
Do not assume that a version listed for one platform is downloadable for every other platform. The official pages referenced here do not provide a complete, current operating-system and architecture matrix, so verify the exact target in the dashboard before building an automated install around it. A channel’s “latest” version can change; use an exact version when repeatability matters.
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 & 11Crashes, 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 minuteInstall the latest available Stable shell
Run this from a terminal with npx available:
npx @puppeteer/browsers install chrome-headless-shell@stableThis asks the Puppeteer browsers utility to install the latest available Stable-channel Chrome Headless Shell. It is the documented channel-based install command. It does not mean the same version will be selected forever: Stable advances, so separate installs made later can retrieve a newer build.
- Confirm the Stable artifact is available for the platform where the browser will run.
- Open a terminal in the environment where you want the browser installed.
- Run the command above and wait for the utility to finish.
- Read the utility’s output to confirm whether installation completed and where it placed the browser; use the location reported by your run rather than assuming a fixed path.
- Configure your automation to use the installed shell, or use Puppeteer’s shell mode as described below.
The command uses npx to invoke @puppeteer/browsers. If the terminal reports that npx is unavailable, resolve the Node.js/npm setup for that machine before retrying; that error is about the command environment, not evidence that the shell artifact is unavailable. The available Chrome documentation does not specify one universal install path or dependency fix for every operating system.
Pin a specific version for reproducible runs
To install a particular release, replace stable with its exact version string. Chrome for Developers gives this as an example:
npx @puppeteer/browsers install [email protected]120.0.6098.0 is an example from the documentation, not a statement that it is the latest build or that the artifact remains available for every platform. Check the availability dashboard or Chrome for Testing’s JSON API first, then substitute the version confirmed for your target.
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Clear out junk files and repair common Windows errors3Scan for outdated or missing drivers - takes under a minutePinning matters in CI and other repeated runs: if each run asks for @stable, a later run may fetch a different browser release after the channel advances. Chrome for Testing is designed to let teams fetch and pin versions so test environments can stay consistent across repeated runs. Record the exact browser version alongside the code or test configuration that depends on it, and update it deliberately when you want to validate a newer release.
Select the installed browser in Puppeteer
If your project uses Puppeteer, decide whether you need a manual download at all. Chrome’s automation overview says Puppeteer automatically downloads a compatible Chrome for Testing browser by default, so a separate install is unnecessary for many projects. Manual installation is useful when you specifically need to manage which browser build is present or when your workflow calls for the standalone shell.
For Puppeteer’s launch configuration, the documented mode values are:
headless: 'shell'selects Chrome Headless Shell.headless: trueselects modern unified Headless.
Use the value that matches the browser and fidelity requirements of the test, rather than treating the two settings as interchangeable names for the same implementation. If you have manually installed a browser, confirm that your project’s Puppeteer setup is actually configured to use that installation; merely downloading a binary does not, by itself, establish which executable a particular project launches.
Chrome’s automation overview, last updated 2026-08-04 UTC, discusses compatible Chrome for Testing downloads and version pinning in automation. For project-specific Puppeteer configuration, consult the documentation for the Puppeteer version used by that project; the Chrome materials cited here establish the mode values and default-download behavior, but not every project’s executable-path configuration.
Troubleshoot common installation problems
The command cannot find npx
The terminal cannot invoke the command-line entry point. Check that Node.js/npm is installed and available in the terminal’s environment, or use a terminal with the correct environment loaded. Then rerun the documented install command. This diagnosis does not identify a particular operating-system package or fix; the right setup depends on how Node.js is managed on the target machine.
The requested version cannot be downloaded
Check that the version is listed for Chrome Headless Shell and that the artifact is available for the exact operating system and CPU architecture. A version string in an example or a result for a different platform does not prove availability for your target. If you do not require a fixed version, try the Stable-channel command instead.
The install succeeds but automation launches another browser
Installation and browser selection are separate steps. In Puppeteer, verify whether the project is using its automatically downloaded compatible Chrome for Testing browser or the manually installed shell, and set the headless mode appropriate to your intended browser. Use headless: 'shell' for the shell and headless: true for unified Headless.
Rank #4
A test behaves differently in shell and unified Headless
First confirm which mode the test actually launches. Then assess whether the test requires regular Chrome’s more authentic, feature-rich behavior or whether the shell’s lighter dependency profile is suitable. Chrome’s documentation supports that workload-based distinction, but it does not supply a universal compatibility list or a diagnosis for every site-specific failure. Do not infer a performance improvement solely from the shell’s lighter description.
A Linux environment reports missing libraries or display-related problems
Check the artifact and environment you selected, then consult documentation specific to that platform and deployment. Chrome’s shell documentation describes the shell as not requiring X11/Wayland or D-Bus, but the official materials cited here do not establish a complete Linux distribution dependency list or universal container flags. Avoid applying package names or launch options meant for a different distribution without confirming that they match your environment.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Or skip the browser setup
If the goal is to capture website screenshots rather than run browser automation or tests, ScreenshotNeo provides a screenshot API and MCP server. Its cURL request is:
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 setup and options. ScreenshotNeo accepts cookie and consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each cleanup step can be turned off. Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and the response identifies the page verdict and billing status in headers. An MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients.
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 →The Free plan includes 1,000 screenshots a month without a card. Paid plans start at $5 for 3,000 shots; all plans include every feature, and yearly billing gives two months free. ScreenshotNeo is an alternative for taking captures, not a replacement for installing Headless Shell when a project needs that browser binary for automation or testing. Sign up for ScreenshotNeo’s free plan to get 1,000 screenshots a month with no card.
Sources and version context
The install commands, channel and availability guidance, and shell description come from Chrome for Developers’ “Headless Chrome shell” documentation, which is labeled deprecated and includes older material; the standalone-binary download section is the relevant install guidance. The distinction between unified Headless and the standalone shell, including Puppeteer’s headless values, comes from Chrome for Developers’ “Chrome Headless mode” page. Automatic compatible browser downloads, version pinning, and CI context come from Chrome for Developers’ automation overview, last updated 2026-08-04 UTC. Check the current Chrome for Testing availability dashboard or JSON API before relying on a channel or version in a build script.
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.
