Yes. Playwright supports headless browser execution, and BrowserType.launch() uses headless: true by default. Your tests and scripts run without opening a visible browser window. Set headless: false when you need to watch the browser for local debugging.
What Playwright’s headless mode does
Headless mode runs Chromium, Firefox or WebKit automation without displaying a browser window on your desktop. Playwright still creates a browser process, page, context and DOM, so navigation, locators, clicks, form entry and assertions work in the same general way as they do in a visible session.
The important default is on the launch method: headless is true unless you override it. A normal launch therefore runs headlessly:
const { chromium } = require('playwright');
const browser = await chromium.launch(); // headless: true by defaultTo make the setting explicit, pass headless: true. To open a visible window, pass headless: false.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →#1 Best Overall
Minimal working examples
Node.js: default headless launch
Install Playwright in your project, then run a script such as this:
const { chromium } = require('playwright');
(async () => {
const browser = await chromium.launch({ headless: true });
const page = await browser.newPage();
await page.goto('https://example.com', { waitUntil: 'domcontentloaded' });
console.log(await page.title());
await browser.close();
})();Because headless is already the default, this is equivalent:
const browser = await chromium.launch();Always close the browser in scripts that finish on their own. Closing releases the browser process and prevents a CI job from hanging while it waits for an open connection.
Node.js: headed mode for debugging
const { chromium } = require('playwright');
(async () => {
const browser = await chromium.launch({ headless: false });
const page = await browser.newPage();
await page.goto('https://example.com');
await page.pause(); // inspect the page while the window is visible
await browser.close();
})();Use this on a machine with a graphical desktop. A headless CI runner normally cannot display this window unless it has a display server configured.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Python: synchronous API
from playwright.sync_api import sync_playwright
with sync_playwright() as p:
browser = p.chromium.launch(headless=True)
page = browser.new_page()
page.goto("https://example.com", wait_until="domcontentloaded")
print(page.title())
browser.close()For local inspection, change the launch call to p.chromium.launch(headless=False).
Playwright Test configuration
Playwright Test projects can choose a browser channel in their configuration. This example opts into the newer Chromium headless implementation:
import { defineConfig, devices } from '@playwright/test';
export default defineConfig({
projects: [
{
name: 'chromium-new-headless',
use: {
...devices['Desktop Chrome'],
channel: 'chromium',
},
},
],
});That project remains headless unless you set a launch option or test configuration that turns it off. For a one-off headed run, use the headed option supported by your Playwright Test command or configure the project with headless: false through its launch settings.
Which headless implementation are you running?
“Headless Playwright” can refer to more than one Chromium implementation. The choice affects the browser binary, installation, and how closely rendering matches a visible Chrome or Edge session.
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 problems| Configuration | Visibility | Runtime | Best fit |
|---|---|---|---|
| Default bundled Chromium | Headless by default | Playwright’s separate Chromium headless shell | General automation and unattended CI |
channel: 'chromium' |
Headless unless changed | Newer Chrome-style headless implementation | When you want the newer Chromium headless behavior |
| Chrome channel | Headless or headed, depending on launch settings | Chrome’s headless implementation | Testing against the installed/branded Chrome channel |
| Microsoft Edge channel | Headless or headed, depending on launch settings | Edge’s headless implementation | Testing against the installed/branded Edge channel |
Any launch with headless: false |
Visible window | Regular headed browser build | Local visual debugging |
The default Chromium headless shell
Playwright ships a regular Chromium build for headed operations and a separate Chromium headless shell for headless mode. The shell is intended for jobs that never need to show a window. It is therefore a useful installation target for CI environments that only execute headlessly.
The newer Chromium headless mode
Set the Chromium channel explicitly when you want the newer Chrome-style headless implementation:
const { chromium } = require('playwright');
const browser = await chromium.launch({
channel: 'chromium',
headless: true,
});The API reference identifies the chromium channel as the opt-in for this new headless mode. It is still headless; the distinction is which Chromium implementation performs the rendering.
Chrome and Edge channels
Chrome and Microsoft Edge channels have headless implementations that are closer to their headed behavior. They can therefore differ from Playwright’s default Chromium headless shell. If a pixel-sensitive screenshot, font, media-query or browser-specific behavior matters, keep the channel fixed and use the same channel in local development and CI.
Outdated 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 matchWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallInstalling for headless-only CI
You do not need a visible desktop to run headless tests, but the selected browser binaries still must be installed on the runner. For a job that will only use the Chromium headless shell, Playwright documents this command:
npx playwright install --with-deps --only-shell--with-deps installs required operating-system packages where the runner supports that workflow, while --only-shell avoids installing the regular Chromium build. If the same machine must also run headed sessions or use another browser, install the corresponding full browser packages instead of restricting the installation to the shell.
- Install your project dependencies, including Playwright.
- Install the browser channel your tests declare. Use
npx playwright install --with-deps --only-shellfor a Chromium headless-shell-only job. - Launch without a display requirement by leaving
headlessat its default or settingheadless: true. - Run the test command and preserve the same channel setting in every environment.
Headless versus headed: practical trade-offs
- Visibility: headless runs have no browser window; headed runs let you watch every navigation and interaction.
- CI suitability: headless is the straightforward choice for unattended runners, containers and scheduled jobs.
- Debugging: headed mode is easier when you need to see a popup, redirect, focus change or unexpected layout. Reproduce the failing test locally with
headless: false. - Installation footprint: a headless-only Chromium job can install only the documented shell, while headed workflows need the regular browser build.
- Rendering consistency: the default Chromium shell, the newer
chromiumchannel and branded Chrome or Edge channels are different runtimes. Do not assume their screenshots are byte-for-byte identical. - Resource behavior: headless removes the cost of drawing a desktop window, but page scripts, network requests and layout work still run. A headless test can remain slow if the site itself is slow.
How to debug a headless failure
- Run the same test locally with
headless: falseso you can observe the page. - Keep the browser channel unchanged while reproducing the failure. Switching from the default shell to Chrome can hide a channel-specific issue.
- Log the URL after each navigation and add assertions for the page state you require, such as a visible sign-in form or a completed redirect.
- If the visible run works but CI does not, compare the installed browser channel and operating-system dependencies before changing application code.
- After fixing the issue, return CI to
headless: true(or the default) and retain the headed configuration only as a local debugging path.
Common errors and fixes
| Symptom | Likely cause | Fix |
|---|---|---|
| No window appears | The launch is headless, which is the default. | Use headless: false when you need a visible browser. |
| The process fails before the first page loads | The required browser binary or Linux dependencies are missing. | Install the browser for the selected channel; for Chromium shell-only CI, run npx playwright install --with-deps --only-shell. |
| A test passes headed but fails headless | The channel, viewport, timing or page rendering differs. | Reproduce with the same channel and settings, then inspect the failing navigation or locator in headed mode. |
| Screenshots differ after a browser change | You moved between the default shell, the new chromium channel, Chrome or Edge. |
Pin one channel for comparison and use that same channel in local and CI runs. |
| A CI job hangs after tests finish | A browser or context was left open. | Close contexts and the browser in teardown; in standalone scripts, call await browser.close(). |
| Headless launch works locally but not on the runner | The runner lacks the browser package or system dependencies. | Install dependencies on the runner and verify that the installed binary matches the channel in your configuration. |
Or skip the browser setup
If your goal is simply to obtain a clean screenshot rather than maintain a Playwright environment, ScreenshotNeo provides a one-request website screenshot API. It accepts consent banners before capture and removes more than 60 known consent platforms, newsletter popups and chat widgets; each step can be disabled. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads and cache hits are not billed, and the response identifies the result with X-Page-Verdict and X-Billed headers. ScreenshotNeo also offers an MCP server with take_screenshot, get_page_info and capture_pdf tools for Claude, Cursor and other MCP clients.
Use the API documentation at https://screenshotneo.com/docs/ for authentication and options. The following calls are runnable once you replace YOUR_API_KEY:
cURL
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpPython
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)Node.js
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);The Free plan includes 1,000 screenshots per month with no card. Paid plans start at $5 for 3,000 screenshots, and every feature is included on every plan. Sign up for the free ScreenshotNeo plan to try it without installing a browser.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.FAQ
Can one project use both headless and headed runs?
Yes. Keep the normal CI launch headless and provide a separate local configuration or command that sets headless: false for investigation.
Is the headless shell the same binary as headed Chromium?
No. Playwright documents a regular Chromium build for headed operations and a separate Chromium headless shell for headless mode.
When should I select channel: 'chromium'?
Select it when you specifically need the newer Chrome-style Chromium headless implementation rather than Playwright’s default headless shell.
Can Chrome or Edge headless behavior differ from Playwright’s default?
Yes. Their headless implementations are closer to headed behavior, so channel choice can affect rendering and should be kept consistent for comparable results.
Frequently Asked Questions
Can one project use both headless and headed runs?
Yes. Keep CI headless and provide a separate local configuration with headless: false for investigation.
Is the headless shell the same binary as headed Chromium?
No. Playwright ships a regular Chromium build for headed operations and a separate Chromium headless shell.
When should I select channel: 'chromium'?
Use it when you need the newer Chrome-style Chromium headless implementation instead of the default headless shell.
Can Chrome or Edge headless behavior differ from Playwright’s default?
Yes. Their headless implementations are closer to headed behavior, so keep the channel consistent when comparing results.
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.
