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 →Headless mode in Selenium runs a real browser without displaying its normal window. Your WebDriver code still starts Chrome, Firefox, or another supported browser, loads pages, executes JavaScript and exposes the usual automation APIs; the difference is that no browser window is shown on the desktop. Selenium configures this at browser startup through an options object and a browser argument. For current Chrome sessions, use --headless=new.
Headless versus headed Selenium
| Aspect | Headed run | Headless run |
|---|---|---|
| Window | A normal browser window is displayed. | No normal browser window is displayed. |
| Browser process | A browser is launched and controlled by WebDriver. | A browser is still launched and controlled by WebDriver. |
| Configuration | Default browser options are usually sufficient. | An options argument such as Chrome’s --headless=new is supplied before the session starts. |
| Typical environment | Useful when you need to watch a test interact with the page. | Useful for CI, servers and scheduled jobs where no graphical desktop is available. |
Headless is an execution mode, not a separate Selenium product or a different WebDriver API. Selenium’s project description calls it an execution mode for Firefox and Chromium-based browsers. The visibility distinction is established; claims that headless is always faster, more stable or pixel-identical to headed Chrome are not universal guarantees. Rendering, timing and resource behavior still depend on the browser version, operating system, page and configuration.
Set up headless Chrome with current Selenium
Prerequisites
- Install a current Selenium binding. For Python, run
python -m pip install -U selenium. - Install Chrome and check its version. Selenium’s Chrome guidance says Selenium 4 supports Chrome 75 and newer, while Chrome and ChromeDriver major versions should match; verify current support for your exact versions when diagnosing a failure.
- Selenium Manager has been bundled with Selenium releases since 4.6 and can obtain a driver under supported network and platform conditions. An offline or restricted machine may still require a driver installed and configured by your environment.
Minimal Python example
from selenium import webdriver
options = webdriver.ChromeOptions()
options.add_argument("--headless=new")
driver = webdriver.Chrome(options=options)
try:
driver.get("https://example.com")
print(driver.title)
finally:
driver.quit()The option must be present when webdriver.Chrome creates the session. The try/finally block closes Chrome even if navigation or an assertion raises an exception. A successful run prints the page title and does not open a visible window.
Make the run reproducible
- Set a deliberate viewport with
driver.set_window_size(width, height)when your assertions depend on responsive layout. - Use explicit waits for a condition or element instead of assuming that a fixed sleep represents page readiness.
- Capture diagnostics on failure, such as the current URL, page source and a screenshot, before calling
quit(). - Run the same browser and driver major versions in development and CI when comparing results.
Why older examples use different APIs
Selenium deprecated its headless convenience method in version 4.8 and removed it in 4.10. Code such as options.set_headless(True) or a binding-specific setHeadless call should be replaced with a browser argument in the options object.
Recommended Free Tools
#1 Best Overall
Chrome’s flags also changed during the Chromium transition. Selenium’s January 2023 migration notes identify --headless=chrome for Chrome versions 96 through 108 and --headless=new from version 109. Those are historical compatibility notes, not instructions to keep old flags forever. The current Chrome-specific Selenium examples use --headless=new. A Selenium 4.18 release note also recorded a Chrome headless naming change and advised switching to the new flag.
Browser-specific differences
Firefox
Do not copy Chrome’s --headless=new argument into every browser configuration. Selenium documents Firefox support through Firefox-specific options; its Firefox page states that Selenium 4 requires Firefox 78 or newer and recommends the latest geckodriver. Check the current Firefox binding and browser documentation for the exact option syntax used by your version.
Edge and other Chromium browsers
Chromium-based browsers share implementation history, but each WebDriver binding and browser release can have its own supported arguments. Create that browser’s options class, consult its current documentation and verify the resulting session rather than assuming Chrome flags apply unchanged.
Remote WebDriver
For a remote session, the options instance sent in the capabilities determines which browser is requested. Add the headless argument to that browser’s options before constructing the remote driver, and confirm that the remote node has the requested browser and driver installed. A local Selenium Manager installation cannot repair a missing or incompatible browser on a remote machine.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Fix the driver behind crashes, sound loss and screen glitches3Repair Windows errors before they cause bigger problemsHeadless and headed runs in testing
Use headless mode when a visible desktop is unavailable or when a job should run without opening windows. Keep a headed configuration available while developing selectors and debugging visual behavior. If a test is sensitive to layout, fonts, GPU behavior, window size or timing, compare the modes in the same environment and treat any difference as an environment-specific finding rather than an inherent property of headless Selenium.
Headless does not make a page less observable to the page itself, does not remove authentication requirements and does not bypass bot checks. It only changes how the browser is displayed. Your test still needs valid credentials, network access, waits and appropriate handling for dialogs, permissions and downloads.
Troubleshoot common failures
“SessionNotCreatedException” or a version mismatch
Cause: Chrome and the driver have incompatible major versions, or the remote node has a different browser than expected.
Fix: Record the Chrome and driver versions, align their major versions, update Selenium if appropriate and retry on the same machine. Do not assume a driver downloaded for one host is correct for another.
set_headless or setHeadless is missing
Cause: The convenience API was removed in Selenium 4.10 after deprecation in 4.8.
Fix: Replace it with options.add_argument("--headless=new") for current Chrome, or the documented option for your selected browser.
The driver cannot be downloaded
Cause: Selenium Manager needs network access or a supported platform path, but the machine is offline, proxied or restricted.
Fix: Provide a driver through your organization’s approved installation process, configure the executable path as supported by your language binding and verify browser-driver compatibility.
Rank #3
A window still appears
Cause: The argument was added to a different options object, added after the driver session was created or omitted from the code path used in CI.
Fix: Construct one options object, add --headless=new before webdriver.Chrome(options=options), and log the configuration used by the failing job.
The session starts and then closes
Cause: An exception, an early process exit or an unconditional quit() executes before your diagnostic code.
Fix: Keep navigation and assertions inside try, collect the URL, title and failure artifacts in an except or teardown hook, then close the driver in finally.
Free tools Windows power users keep installed
One-click scans. No signup required.
Remote execution uses the wrong browser
Cause: The requested options were not serialized, or the remote grid selected a node that does not provide the requested browser.
Fix: Pass the browser options directly to the remote driver, inspect the node’s session capabilities and correct the grid’s browser-selection configuration.
Performance, reliability and cost considerations
Headless mode removes the visible window, but the supplied Selenium material does not establish a universal speed or reliability improvement. Measure your own workflow if startup time or throughput matters. More predictable gains usually come from reducing unnecessary navigations, waiting on the right conditions, reusing a session where safe and keeping browser and driver versions aligned.
Headless runs still consume browser, driver and page resources. A CI worker needs enough memory and CPU for the browser and the site under test. If a test fails only in headless mode, compare viewport, browser version, fonts, permissions, download paths, network policy and timing before changing assertions.
Or skip the browser setup
If your goal is a rendered image or PDF rather than interactive Selenium automation, ScreenshotNeo provides a website screenshot API and MCP server. One request can capture a URL without maintaining Chrome, ChromeDriver or a display server.
Using the API requires an access key. The following calls are documented at ScreenshotNeo’s API documentation.
cURL
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com -o shot.webpPython
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://example.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)Node.js
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://example.com' }); const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);ScreenshotNeo accepts options for full-page captures with lazy images loaded, CSS-selector element capture, dark mode, 12 device presets or a custom viewport, retina scale, PDF paper size/margins/orientation/page ranges, HTML/CSS rendering, custom JavaScript and CSS, pre-capture clicks, hidden selectors, selector or network-idle waits, ad/tracker/request/resource blocking, custom headers/cookies/user agents and Authorization, timezone and geolocation, transparent backgrounds, image resizing, user-selected cache TTLs, signed public image links, asynchronous jobs with signed webhooks, bulk capture of up to 100 URLs per call, a usage API and an OpenAPI specification. Parameter names used by other screenshot APIs also work to ease migration.
Before capture, it accepts the cookie or consent banner like a visitor and removes more than 60 known consent platforms, newsletter popups and chat widgets; each cleanup step can be disabled. Only clean shots are billed. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads and cache hits cost nothing, 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 for Claude, Cursor and other MCP clients.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
| Plan | Monthly shots | Price |
|---|---|---|
| Free | 1,000 | $0, no card |
| Starter | 3,000 | $5 |
| Growth | 15,000 | $15 |
| Pro | 60,000 | $39 |
| Scale | 250,000 | $99 |
| Business | 1,000,000 | $249 |
Every feature is included on every plan, and yearly billing provides two months free. You can start with 1,000 free screenshots a month with no card; paid plans start at $5 for 3,000 shots.
Best Value
Frequently asked questions
Can I switch an existing WebDriver session between headless and headed modes?
No. The display mode is a startup option. Quit the current session and create a new one with the desired options.
Does headless mode remove browser automation from a page?
No. It changes display, not the fact that Selenium is controlling a browser. Authentication, permissions, network access and site-specific automation behavior still apply.
Should visual checks run only headless?
Use the mode that matches the environment you need to validate, and compare with a headed run when a layout or rendering discrepancy matters.
Frequently Asked Questions
Can I switch an existing WebDriver session between headless and headed modes?
No. The display mode is selected at startup; create a new session with the other options.
Does headless mode remove browser automation from a page?
No. It changes display only. Authentication, permissions, network access and site-specific behavior still apply.
Should visual checks run only headless?
Use the mode that matches the environment you need to validate, and compare with headed execution when rendering differences matter.
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.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →
