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 →Yes. Playwright supports headless browser execution, and the headless launch option defaults to true. A normal launch therefore runs without opening a visible browser window. Set headless: false when you need to watch the browser while debugging.
What “headless” means in Playwright
Headless mode runs a real Playwright-controlled browser without displaying its window on your desktop. Your code still launches a browser process, creates contexts and pages, loads sites, executes JavaScript and can take screenshots or produce PDFs. The difference is visibility, not whether browser automation occurs.
Playwright’s BrowserType API defines headless as whether to run in headless mode, with a default value of true. The default applies when you call chromium.launch(), firefox.launch() or webkit.launch() without overriding the option.
Is Playwright headless by default?
Yes. These two launches are equivalent:
const { chromium } = require('playwright');
const browser1 = await chromium.launch();
const browser2 = await chromium.launch({ headless: true });Neither launch opens a browser window. In unattended test runners and CI systems, this default is useful because the job does not depend on a desktop session.
#1 Best Overall
Open a visible browser for debugging
Pass headless: false when you want to see each navigation and interaction:
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.waitForTimeout(3000);
await browser.close();
})();This headed mode is normally the fastest way to discover an incorrect selector, an unexpected redirect or a page state that is hard to understand from logs alone. Close the browser in a finally block in production scripts so failures do not leave processes running.
Default Chromium headless shell versus new headless mode
Playwright ships a regular Chromium build for headed operations and a separate Chromium headless shell for headless mode. That means the default Chromium launch is not simply the regular desktop binary with its window hidden; it uses a dedicated headless build.
Playwright also supports Chrome’s newer headless implementation. Opt into it by selecting the chromium browser channel:
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Repair Windows errors before they cause bigger problems3Fix the driver behind crashes, sound loss and screen glitchesconst { chromium } = require('playwright');
(async () => {
const browser = await chromium.launch({
channel: 'chromium',
headless: true
});
const page = await browser.newPage();
await page.goto('https://example.com');
console.log(await page.title());
await browser.close();
})();The channel choice changes the browser implementation used for headless execution. If pixel output, rendering details or browser-specific behavior matters to your tests, keep the channel fixed in every environment and validate that configuration rather than assuming all headless modes are identical.
How Chrome and Edge channels fit in
Chrome and Microsoft Edge channels have a headless implementation closer to their headed behavior. Their results can therefore differ from Playwright’s default Chromium headless shell. Use a branded channel when your application must be tested against that installed browser, and record the channel as part of the test configuration so local and CI runs use the same engine.
Choosing a configuration
| Configuration | Window visible? | Runtime | Best use | Installation note |
|---|---|---|---|---|
chromium.launch() |
No | Playwright’s Chromium headless shell | Default automation and CI | Install the normal Playwright browsers, or the shell-only package for headless-only jobs |
chromium.launch({ headless: false }) |
Yes | Regular Chromium build | Local visual debugging | Requires the regular browser build and a usable desktop display |
chromium.launch({ channel: 'chromium' }) |
No when headless remains true |
New Chrome-style headless implementation | Testing the newer Chromium headless behavior | Install the channel selected by your Playwright setup |
| Chrome or Edge channel | No when headless | Branded browser headless implementation | Browser-specific compatibility checks | The matching channel must be available in the environment |
Install only what a headless CI job needs
If a job will never open a headed browser, Playwright’s browser guide documents this installation command:
npx playwright install --with-deps --only-shell--with-deps installs the operating-system dependencies supported by the command, while --only-shell installs only the Chromium headless shell instead of the full regular browser build. This can reduce the installation footprint for dedicated headless workers.
Recommended Free Tools
Do not use a shell-only installation for a workflow that later switches to headless: false or needs a regular Chromium channel. Install the full browser set required by that workflow instead.
Runnable Node.js examples
Minimal headless screenshot
const { chromium } = require('playwright');
(async () => {
const browser = await chromium.launch({ headless: true });
try {
const page = await browser.newPage({ viewport: { width: 1440, height: 900 } });
await page.goto('https://example.com', { waitUntil: 'load' });
await page.screenshot({ path: 'example.png', fullPage: true });
} finally {
await browser.close();
}
})();Use headed mode only when a debug flag is set
const { chromium } = require('playwright');
(async () => {
const debug = process.env.PW headed === '1';
const browser = await chromium.launch({ headless: !debug });
try {
const page = await browser.newPage();
await page.goto('https://example.com');
console.log(await page.title());
} finally {
await browser.close();
}
})();In the example above, set an environment variable before running the script when you need a window. Avoid embedding a machine-specific decision in the test itself; a CI pipeline can keep the default headless path while a developer opts into headed debugging locally. (Use a variable name without spaces in real code, such as PW_HEADED.)
Playwright Test configuration
With Playwright Test, set the channel in a project when you want the new Chromium headless implementation:
import { defineConfig, devices } from '@playwright/test';
export default defineConfig({
projects: [
{
name: 'chromium-new-headless',
use: {
...devices['Desktop Chrome'],
channel: 'chromium'
}
}
]
});The project remains headless unless you override the launch setting. For a temporary headed run, pass the corresponding command-line or configuration override supported by your test setup; keep the checked-in project configuration stable so results remain comparable.
Python equivalent
The same distinction is available in Playwright’s Python API:
from playwright.sync_api import sync_playwright
with sync_playwright() as p:
browser = p.chromium.launch(headless=True)
try:
page = browser.new_page()
page.goto('https://example.com')
page.screenshot(path='example.png', full_page=True)
finally:
browser.close()For a visible browser, change only the launch argument to headless=False. Keeping all other code unchanged is useful when diagnosing whether a failure is caused by rendering visibility or by the test itself.
What changes between headless and headed runs?
Visibility and debugging
Headless runs provide no window to inspect manually, so rely on assertions, logs and saved artifacts such as screenshots. Headed runs let you watch the same interactions and are better for quickly identifying selector and timing mistakes.
Browser implementation
Default Chromium headless uses the separate headless shell. The chromium channel selects the newer Chrome-style headless implementation, while Chrome and Edge channels use their own implementations. Rendering-sensitive tests should pin the channel instead of mixing configurations.
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 →Resource footprint
A headless-only worker can install just the shell with npx playwright install --with-deps --only-shell. A machine that alternates between headed and headless modes needs the regular browser build as well.
Troubleshooting headless Playwright
A browser window never appears
That is expected when headless is true or omitted. Set headless: false and run on a machine with a desktop display when you need a visible window.
The launch fails after a shell-only install
A shell-only installation supplies the headless shell, not the regular headed browser. Install the full browser required by the workflow, or keep the launch headless.
Headless output differs from headed output
Check the browser channel first. The default shell, the chromium channel and branded Chrome or Edge channels can use different headless implementations. Run both configurations with the same viewport, URL and test data before attributing a difference to application code.
Free tools Windows power users keep installed
One-click scans. No signup required.
CI cannot start a headed browser
Headed mode requires a usable display environment. Keep CI jobs headless, and reproduce the failing test on a desktop machine with headless: false when visual inspection is needed.
The page appears incomplete
Headless mode does not guarantee that a page has finished all application work at the instant navigation returns. Add an explicit wait for the application state your test needs, then capture a screenshot or log the state. If the result still differs by browser, compare the shell and channel choices.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Performance, reliability and cost considerations
Headless is the practical default for unattended automation because it avoids a visible-window dependency and permits shell-only installation. The main reliability decision is consistency: use the same Playwright version, browser channel and installation strategy across local and CI environments. If a test depends on Chromium’s rendering details, switching between the default shell and a branded channel can create differences that look like flaky application behavior.
Headed mode is valuable during diagnosis but adds a display prerequisite. A useful workflow is to run the test headless by default, save failure artifacts, and reproduce only the failing case in headed mode. This keeps routine runs suitable for CI while preserving a fast path to visual debugging.
Or skip the browser setup
If your actual requirement is simply a clean image or PDF of a URL rather than browser assertions, ScreenshotNeo provides a website screenshot API and MCP server. It accepts consent banners before capture and removes more than 60 known consent platforms, newsletter popups and chat widgets; each cleanup 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. Its MCP server exposes take_screenshot, get_page_info and capture_pdf tools to Claude, Cursor and other MCP clients.
One GET request returns PNG, JPEG, WebP or PDF output:
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 documentation for the full option set, including full-page and element capture, device presets, dark mode, custom CSS and JavaScript, waits, request blocking, headers and cookies, geolocation, PDF page ranges, resizing, caching, signed links, asynchronous webhooks and bulk capture.
Python:
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 available on every plan. Create a free ScreenshotNeo account to get started.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
FAQ
Can I use headless and headed modes in the same project?
Yes. Keep the browser and test code the same, and vary the launch or project configuration. This is useful when CI stays headless while local investigation uses a visible window.
Does selecting the chromium channel make the browser headed?
No. The channel selects a Chromium implementation. Visibility is still controlled separately by the headless option, which remains true unless you set it to false.
Should every screenshot test use the new headless mode?
Not automatically. Choose the implementation that matches the browser behavior you need to validate, then keep that choice consistent across environments and document it in your test configuration.
Frequently Asked Questions
Can I use headless and headed modes in the same project?
Yes. Keep the browser and test code the same, and vary the launch or project configuration. This is useful when CI stays headless while local investigation uses a visible window.
Does selecting the chromium channel make the browser headed?
No. The channel selects a Chromium implementation. Visibility is still controlled separately by the headless option, which remains true unless you set it to false.
Should every screenshot test use the new headless mode?
Not automatically. Choose the implementation that matches the browser behavior you need to validate, then keep that choice consistent across environments and document it in your test configuration.
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.
