Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
Chrome Headless Shell is a standalone binary for Chrome’s older, or “legacy,” Headless implementation. Developers use it to automate browser tasks without a visible window—often to render screenshots or PDFs, inspect a page’s DOM, or run scraping workflows. It is distinct from modern Chrome Headless: in Puppeteer, choose headless: 'shell' for the Shell binary and headless: true for modern Headless.
What Chrome Headless Shell is—and what it is not
Chrome Headless mode runs a browser in an unattended environment without a visible user interface. The older Headless implementation was once included inside the Chrome binary as a separate browser implementation. Since Chrome 132.0.6793.0, that older implementation has been distributed as a standalone binary named chrome-headless-shell, available through Chrome for Testing. Chrome’s Headless documentation distinguishes this binary from modern Headless, which runs the unified Chrome browser without displaying its UI.
In other words, “Headless Shell” means the standalone legacy browser binary; “modern Headless” means Chrome itself, running without a visible window. They both enable automated browser work, but they are not interchangeable in every workflow. Shell is a lightweight wrapper around Chromium’s //content module, with substantially fewer dependencies. That can help in some server or constrained environments, but it does not establish that Shell is always faster or behaves exactly like full Chrome. Chrome describes the trade-offs and intended uses.
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Clear out junk files and repair common Windows errorsFree Scan →When to choose Shell or modern Headless
Choose based on the behavior your project needs, not just the fact that both modes lack a visible UI.
#1 Best Overall
| Decision factor | Headless Shell | Modern Chrome Headless |
|---|---|---|
| Browser fidelity | Useful when a lightweight rendering workflow is sufficient; do not assume it will match regular Chrome in every detail. | Runs the actual Chrome browser implementation, making it the stronger choice when behavior should closely match Chrome. |
| Chrome features | Not the choice identified by Chrome for testing browser extensions. | Chrome recommends it for browser extension tests and high-accuracy end-to-end web app tests. |
| Environment dependencies | Has substantially fewer dependencies, including no X11/Wayland or D-Bus requirement, which may simplify some server deployments. | Use when the broader Chrome implementation and feature coverage matter more than a reduced dependency profile. |
| Typical tasks | Automated screenshotting and web scraping when the full Chrome functionality is unnecessary. | End-to-end tests and workflows that depend on Chrome-specific behavior or features. |
| Reproducible builds | Obtain a versioned binary through Chrome for Testing and pin the version your project uses. | Chrome for Testing also distributes versioned browser binaries; pin a build when repeatability is important. |
Chrome calls Shell potentially more performant in some circumstances, but the available guidance does not establish a numerical benchmark or guarantee a speed improvement. Measure your own workload if throughput or latency determines the choice. See Chrome’s guidance on Headless Shell and modern Headless.
How to download Chrome Headless Shell
Chrome for Testing distributes versioned browser binaries and matching ChromeDriver releases. Chrome’s Shell guide shows installation with the @puppeteer/browsers command-line utility:
npx @puppeteer/browsers install chrome-headless-shell@stableFor a deliberately pinned build, the guide also demonstrates a version-specific command:
npx @puppeteer/browsers install [email protected]The version in that example illustrates the command format; it is not a recommendation to install that older build now. Use the current release channel for routine work, or choose and pin a version that suits your project’s compatibility requirements. Chrome for Testing also provides JSON endpoints and an availability dashboard for scripts that need to discover available builds. Consult Chrome’s Headless Shell instructions and the Chrome for Testing overview for current distribution details.
Use Headless Shell from Puppeteer
Puppeteer is a JavaScript library for controlling Chrome and Firefox through Chrome DevTools Protocol and WebDriver BiDi. It supports page interaction, navigation, screenshots, PDFs, network interception, and UI testing. Set the headless option explicitly so the selected browser mode is clear:
import puppeteer from 'puppeteer';
const browser = await puppeteer.launch({
headless: 'shell', // Standalone Chrome Headless Shell
});
try {
const page = await browser.newPage();
await page.goto('https://example.com/', { waitUntil: 'networkidle0' });
await page.screenshot({ path: 'example.png', fullPage: true });
await page.pdf({ path: 'example.pdf', format: 'A4' });
} finally {
await browser.close();
}The example asks Puppeteer to wait for network activity to settle before capture. A site may continue making requests or render content later, so this wait condition is not a guarantee that every application is fully ready. Choose a readiness condition suited to the page, such as waiting for a known element when the application exposes one. Puppeteer’s installation guide says installing puppeteer automatically downloads Chrome for Testing and a compatible Headless Shell binary. Package-manager install scripts and download behavior can change; check the installed Puppeteer version and installation guidance if the binary is missing.
To select another mode, use headless: true for modern Headless or headless: false to launch Chrome with its visible UI. The distinctions and current launch options are documented in Chrome’s Headless overview and the Puppeteer launch options reference.
Run common tasks from the command line
The Chrome command-line reference documents these capture patterns for Headless mode and Headless Shell. Use the installed binary’s name and path as appropriate for your system.
Serialize the page’s DOM
chrome-headless-shell --dump-dom https://example.com/--dump-dom prints a serialized DOM after Chrome parses the page and runs scripts that may change it. This is not the same as downloading the original response HTML: the output can include changes made by page scripts.
Capture a screenshot
chrome-headless-shell --screenshot --window-size=412,892 https://example.com/--window-size sets the viewport dimensions for this example. The command captures a screenshot; the page’s own rendering and load behavior determine what appears in it.
Print a page to PDF
chrome-headless-shell --print-to-pdf https://example.com/These flags and additional command-line capture options are covered in Chrome’s Headless command-line documentation.
Free tools Windows power users keep installed
One-click scans. No signup required.
Control waits for capture
The --timeout option limits how long a capture operation waits for page loading. --virtual-time-budget fast-forwards page code that depends on timers, which can be useful when content updates after a delay. Neither option guarantees that an application has finished rendering: choose a suitable wait strategy for the site and verify the resulting output. See the official command-line reference for the option syntax and examples.
Test virtual screens and multi-display behavior
Headless mode can use virtual screens independently of physical displays attached to the host. The --screen-info flag configures display properties such as size, origin, scale factor, orientation, and work area. Chrome DevTools Protocol can also add or remove screens while the browser is running. These capabilities can support tests for fullscreen behavior, multiscreen layouts, high-DPI settings, and popups appearing on different screens. Puppeteer can drive these workflows; consult Chrome’s virtual-screen guide for supported controls and examples.
Or skip the browser setup
If your immediate goal is to get a website screenshot rather than manage a local browser binary, ScreenshotNeo offers a screenshot API and MCP server for developers. A single GET request can return a PNG, JPEG, WebP, or PDF. Here is the cURL form:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com -o shot.webpSee the ScreenshotNeo API documentation for the API options and response details. Its clean-shot steps can accept cookie or consent banners and remove more than 60 known consent platforms, newsletter popups, and chat widgets; each step can be turned off. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and responses include X-Page-Verdict and X-Billed headers to identify the outcome. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for AI agents, including Claude, Cursor, and other MCP clients.
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 →The Free plan includes 1,000 screenshots per month with no card required. Paid plans start at $5 for 3,000 screenshots; yearly billing gives two months free, and every feature is available on every plan. Sign up for ScreenshotNeo’s free plan to get 1,000 screenshots a month without a card.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Troubleshoot common problems
The browser binary cannot be found
Puppeteer may not have downloaded a compatible browser, or the install script may not have run. Check the current installation instructions for your package manager, confirm the Puppeteer version and browser cache location, and install the Shell binary with npx @puppeteer/browsers install chrome-headless-shell@stable if appropriate. If you intentionally pinned a version, ensure the installed binary matches the project’s expected build.
The page is blank or missing content in a capture
A screenshot or PDF can be taken before a site’s client-side rendering has completed. A general load or timeout setting may not cover application-specific delays. Wait for a page element that indicates readiness, or use a suitable delay or virtual-time budget for timer-driven updates; inspect the DOM with --dump-dom to see whether scripts changed the page.
A test behaves differently from regular Chrome
First confirm which mode Puppeteer launched: 'shell' selects Headless Shell, whereas true selects modern Headless. If the test depends on Chrome features, extension behavior, or high-fidelity end-to-end behavior, switch to modern Headless and compare results. Shell’s reduced dependency profile is a trade-off, not a promise of identical behavior.
Rank #4
A command-line capture stops waiting too early
Adjust the documented --timeout or --virtual-time-budget options to the page’s loading pattern, but do not treat either as proof the app is ready. For programmatic workflows, wait for a meaningful selector or application state before capturing.
A script needs a repeatable browser build
Use a versioned Chrome for Testing binary rather than relying on an unspecified build, and record the version in the project’s setup. Chrome for Testing provides JSON endpoints and an availability dashboard for discovering builds; pin a build intentionally and update it as part of your normal compatibility process.
Frequently asked questions
Can Chrome Headless Shell run without X11, Wayland, or D-Bus?
Chrome describes Shell as having substantially fewer dependencies, including no X11/Wayland or D-Bus requirement. That can simplify some environments, although your particular host and workflow may have other requirements.
Is Headless Shell the same as ChromeDriver?
No. Headless Shell is a browser binary. Chrome for Testing distributes browser binaries and matching ChromeDriver releases; ChromeDriver is a separate component used to automate Chrome in compatible workflows.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Scan for outdated or missing drivers - takes under a minute3Repair Windows errors before they cause bigger problemsCan I use Headless Shell for extension tests?
Chrome identifies modern Headless as the more suitable option for browser extension tests. Use it when extension behavior is part of the test you need to validate.
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.
