5 min read
Also: Chrome headless mode, chrome --headless, headless=new, chrome-headless-shell, HeadlessChrome, headless Chromium, headless browser
Headless Chrome
Quick answer
Headless Chrome is Chrome running without a visible window, controlled by code through the Chrome DevTools Protocol or ChromeDriver. From a terminal, chrome --headless --screenshot https://example.com saves a screenshot and --print-to-pdf saves a PDF; if it will not start in Docker or CI, see Failed to launch the browser process.
Headless Chrome is Google Chrome running without a visible window. It renders pages and runs JavaScript like normal Chrome and is controlled by code, which makes it the standard engine for automated testing, scraping, screenshots and PDF generation.
Last verified
What people do with Headless Chrome
- Fix "Failed to launch the browser process"
Missing libraries, sandbox and shared-memory problems in containers.
- Fix "Host system is missing dependencies to run browsers"
Install the system packages headless Chromium needs on Linux.
- Fix "DevToolsActivePort file doesn't exist"
Headless Chrome under Selenium crashing on startup.
- Scrape JavaScript pages that come back empty
When you need a real (headless or headed) browser instead of HTTP requests.
- Understand why headless browsers get blocked
The fingerprint and behaviour signals anti-bot systems check.
- Match ChromeDriver to your Chrome
Version matching for Selenium-driven headless runs.
Key facts
| Made by | Google (part of Chrome and Chromium) |
|---|---|
| Introduced | Chrome 59, 2017 |
| New headless mode | Introduced in Chrome 112 (2023); the only mode in the main Chrome binary since Chrome 132 |
| Old headless mode | Removed from Chrome in version 132 (January 2025); now the standalone chrome-headless-shell binary |
| Command-line flag | --headless (equivalent to --headless=new) |
| Controlled through | Chrome DevTools Protocol (Puppeteer, Playwright) or ChromeDriver (Selenium) |
What is headless Chrome?
Headless Chrome is Google Chrome running without a visible window. It loads pages, runs JavaScript, applies CSS, handles cookies and builds the DOM exactly as normal Chrome does, but nothing is drawn on a screen. You control it from the command line or, much more often, from an automation library such as Puppeteer, Playwright or Selenium.
Google added headless mode in Chrome 59 in 2017. Before that, developers used PhantomJS, a separate headless browser based on an older WebKit engine, whose maintainer stepped back once Chrome could do the same job with a current engine.
Old headless, new headless and chrome-headless-shell
Headless Chrome has had two implementations, and the difference explains a lot of confusing behavior:
From Chrome 132 (January 2025), --headless and --headless=new both start the new mode, and --headless=old prints an error instead. The old implementation now ships only as a standalone binary called chrome-headless-shell, available through Chrome for Testing. Puppeteer and Playwright use chrome-headless-shell for some headless configurations because it starts faster, which is why a script can behave differently depending on which binary it launched.
How to run it
From a terminal, you can use headless Chrome without any library:
chrome --headless --dump-dom https://example.com prints the rendered HTMLchrome --headless --screenshot https://example.com saves a screenshotchrome --headless --print-to-pdf https://example.com saves a PDFFor anything interactive, a library connects to the browser over the Chrome DevTools Protocol (Puppeteer, Playwright) or through ChromeDriver (Selenium) and sends commands: go to this URL, click this element, return this text.
What people use it for
Common problems
Content that shows in your browser is missing headless. Many sites serve a different layout to small or unusual viewports. Headless Chrome historically defaulted to an 800x600 window; set an explicit viewport such as 1920x1080.
Being detected and blocked. Headless browsers are a classic bot signal. Default automation sets navigator.webdriver to true; older headless builds put HeadlessChrome in the user agent; and fingerprint checks look at fonts, WebGL, screen dimensions and missing plugins. Anti-bot services such as Cloudflare, DataDome and HUMAN (PerimeterX) combine those with network-level signals. Changing the user agent alone rarely helps, and running headed often passes checks that headless fails.
Fonts, emoji and characters missing in screenshots. Minimal Linux containers lack fonts. Install font packages such as Noto in the image.
Crashes in Docker. Chrome uses /dev/shm for shared memory, which defaults to 64 MB in Docker. Pages crash with "Aw, Snap" or the target closes unexpectedly; increase the shared memory size or pass --disable-dev-shm-usage.
Downloads and file dialogs. Headless Chrome does not show download prompts; you must set a download directory through the automation library.
Remote debugging refused on your normal profile. Since Chrome 136, --remote-debugging-port is ignored when Chrome uses the default user data directory, to stop malware reading real profiles. Pass a separate --user-data-dir.
Headless Chrome and automation
Headless is the default in most automation tools because it is cheaper: no display server and less memory. The trade-off is that it is easier to detect and harder to debug, because you cannot see what went wrong.
Autonoly does not run headless. Its browser is Chromium, controlled by Playwright with patchright, running headed inside a container with a virtual display. That is what makes the live view possible: you can watch the agent work, and take over the browser to solve a challenge or enter a code, then hand it back. Running headed does not make a browser undetectable, and Autonoly does not use proxies or rotate IP addresses, so sites with strict bot protection may still challenge it.
Why It Matters
Most browser automation, from CI test suites to scrapers, runs on headless Chrome. Knowing the difference between old and new headless, and why headless browsers are easier to detect, explains many failures that look like selector or timing bugs.
How Autonoly Solves It
Autonoly runs Chromium headed, not headless, inside an isolated container, using Playwright with patchright. You can watch every step in a live view and take control mid-run, for example to complete an unsupported CAPTCHA, then let the agent continue.
Learn moreExamples
A CI pipeline that launches headless Chrome to run end-to-end tests on every pull request
A script that uses chrome --headless --print-to-pdf to turn a nightly HTML report into a PDF attachment
A scraper that switches from plain HTTP requests to headless Chrome because product prices are loaded by JavaScript
Frequently Asked Questions
What is the difference between headless and headed Chrome?
Headed Chrome draws a window you can see; headless Chrome does the same work without displaying anything. Since the new headless mode, both run the same browser code, so pages behave the same. Headless uses fewer resources and needs no display server.
What is chrome-headless-shell?
It is the old headless implementation, split out of Chrome into a standalone binary. Chrome 132 removed it from the main browser, so --headless=old no longer works there. It starts faster but differs slightly from real Chrome, and it is available through Chrome for Testing.
Why does my scraper work headed but fail headless?
The most common causes are a small default viewport that triggers a mobile or different layout, and bot detection that treats headless browsers more strictly. Set a normal viewport size first, then check whether the site is returning a challenge page instead of content.
Can websites detect headless Chrome?
Often. Default automation sets navigator.webdriver to true, older builds advertise HeadlessChrome in the user agent, and fingerprinting checks screen size, fonts, graphics and many other details. Commercial bot protection combines these with network signals, so no single setting hides it.
How do I run Chrome headless from the command line?
Start Chrome with the --headless flag plus an action, for example --dump-dom to print the rendered HTML, --screenshot to save an image or --print-to-pdf to save a PDF, followed by the URL. For clicking and typing, use Puppeteer, Playwright or Selenium.
Does Autonoly use headless Chrome?
No. Autonoly runs Chromium in headed mode inside a container, controlled by Playwright with patchright. Headed mode is what allows the live view and human takeover. It does not use proxies, so strictly protected sites can still challenge it.
Further reading
Related terms, automations and guides
Where this concept shows up in practice.
Stop reading about automation.
Start automating.
Describe what you need in plain English. Autonoly's AI agent builds and runs the automation for you — no code required.