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 →Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
To run a Selenium 4 test without opening a visible browser window, set the browser’s headless option before creating the WebDriver, then pass that options object to the driver. For Chrome and Edge, use --headless=new; for Firefox, use -headless. Headless mode still runs a browser, so browser startup, driver compatibility, page timing and rendering remain part of the test.
What headless mode changes—and what it does not
Headless mode runs a browser without displaying its graphical window. Your test still navigates pages, finds elements and performs browser actions through WebDriver. It is useful in CI runners and containers that do not have a desktop session, or when you do not need to watch the browser while a test runs.
Headless is not a guarantee that a test will be faster or that it will render identically across every browser and environment. The authoritative guidance here establishes the configuration and compatibility requirements, but no independent fixed performance improvement. If a layout or timing failure appears only in headless mode, compare the same smoke test in headful and headless modes before changing application selectors or adding arbitrary delays.
Free tools Windows power users keep installed
One-click scans. No signup required.
Run a headless Chrome test with Selenium 4
Create a ChromeOptions object, add the headless argument and a fixed viewport, and pass the options into webdriver.Chrome. The following Python example opens a page, checks its title, and always closes the browser—even if navigation or the assertion fails.
#1 Best Overall
from selenium import webdriver
options = webdriver.ChromeOptions()
options.add_argument("--headless=new")
options.add_argument("--window-size=1440,1000")
driver = webdriver.Chrome(options=options)
try:
driver.get("https://example.test")
assert "Example" in driver.title
finally:
driver.quit()Replace https://example.test with the page under test and adjust the title assertion to match your application. The fixed window size makes the viewport explicit, which helps prevent a test from depending on an environment’s default dimensions. Keep the try/finally cleanup pattern in real tests; an unclosed browser process can interfere with later tests in the same worker.
Selenium’s current Chrome documentation says Selenium 4 is compatible with Chrome v75 and greater, and Chrome and ChromeDriver must match on their major version. The same documentation lists --headless=new among common Chrome arguments. Chrome’s own documentation says current Headless and headful modes are unified; from Chrome 132.0.6793.0, the old Headless implementation is available as a separate chrome-headless-shell binary. For ordinary Selenium configuration, use the browser’s current headless mode rather than assuming the old implementation is the default.
Java Chrome example
In Java, configure ChromeOptions before constructing ChromeDriver. This example uses the same headless flag and viewport as the Python version.
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.chrome.ChromeDriver;
import org.openqa.selenium.chrome.ChromeOptions;
public class HeadlessChromeTest {
public static void main(String[] args) {
ChromeOptions options = new ChromeOptions();
options.addArguments("--headless=new", "--window-size=1440,1000");
WebDriver driver = new ChromeDriver(options);
try {
driver.get("https://example.test");
System.out.println(driver.getTitle());
} finally {
driver.quit();
}
}
}Use headless Firefox or Microsoft Edge
The option name differs by browser. Do not copy Chrome’s argument to Firefox. Selenium’s Firefox guidance states that Selenium 4 requires Firefox 78 or greater and recommends the latest geckodriver.
Rank #2
Firefox in Python
from selenium import webdriver
options = webdriver.FirefoxOptions()
options.add_argument("-headless")
options.add_argument("--width=1440")
options.add_argument("--height=1000")
driver = webdriver.Firefox(options=options)
try:
driver.get("https://example.test")
print(driver.title)
finally:
driver.quit()The width and height arguments make the intended viewport explicit. If your test depends on responsive behavior, choose dimensions that correspond to the layout you need to exercise, and use the same values in local and CI runs.
Edge in Python
Use Selenium 4’s Edge WebDriver support and an EdgeOptions object. Microsoft’s Edge WebDriver guidance shows --headless=new for Selenium 4.
from selenium import webdriver
from selenium.webdriver.edge.options import Options
options = Options()
options.add_argument("--headless=new")
driver = webdriver.Edge(options=options)
try:
driver.get("https://example.test")
print(driver.title)
finally:
driver.quit()Microsoft documents the corresponding EdgeOptions approach across Python, Java, C# and JavaScript. Use the built-in Selenium Edge classes rather than the older Selenium 3 Edge tooling.
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Clear out junk files and repair common Windows errors3Scan for outdated or missing drivers - takes under a minuteBrowser arguments and configuration choices
| Browser | Headless argument | Compatibility detail established by the cited project guidance |
|---|---|---|
| Chrome / Chromium | --headless=new |
Selenium 4 supports Chrome v75 and greater; Chrome and ChromeDriver major versions must match. |
| Firefox | -headless |
Selenium 4 requires Firefox 78 or greater; Selenium recommends the latest geckodriver. |
| Microsoft Edge | --headless=new |
Microsoft’s Selenium 4 guidance uses EdgeOptions and the built-in Edge WebDriver classes. |
Set the browser options before driver creation. Other browser options—such as a fixed viewport—belong on the same options object. Avoid adding flags copied from unrelated Docker recipes without understanding their effect. In particular, use --no-sandbox only if the container or runtime requires it and your security model permits it; it is not a universal Selenium fix.
Driver management and version compatibility
Selenium Manager ships with Selenium releases as of 4.6. When you do not provide a driver, Selenium bindings can invoke Selenium Manager to discover, download and cache the required driver. This can simplify local setup, but it does not remove browser/driver compatibility requirements. For Chrome, the browser and ChromeDriver major versions must match.
CI images and browser packages can change independently. If you pin a driver while allowing the browser to update automatically, a previously passing job may start failing after an image refresh. Record the Selenium binding, browser, driver, operating system and container image versions with the test run. Decide deliberately whether the environment pins browser and driver together or allows Selenium Manager to resolve the driver for the installed browser.
Make headless tests dependable in CI
- Confirm the runtime: record Selenium binding, browser, driver, operating system and container image versions. Verify that the expected browser binary is present in the job environment.
- Reproduce visibly when useful: run one failing smoke test with the browser visible, if the environment has a desktop, to distinguish application rendering or test logic issues from browser startup problems.
- Fix state, not elapsed time: use a fixed viewport and wait for the application condition the test needs. An explicit wait tied to an element or state is more reliable than an arbitrary sleep.
- Preserve failure evidence: save a screenshot, page source, console or driver log, and test metadata when a test fails. Headless runs have no visible window to inspect, so artifacts help reveal whether the page was blank, incomplete, differently laid out or blocked before the assertion.
- Close every session: call
quit()in afinallyblock or your test framework’s teardown hook, including after assertion and navigation errors.
For remote execution, Selenium’s Remote WebDriver API accepts browser options together with a Grid URL. The browser session then runs on another host, which can help when a CI container lacks a desktop, when you need to run several browser versions in parallel, or when a hosted grid provides the browsers. The headless arguments still belong to the browser options passed to that remote session. Hosted-grid pricing, supported regions, artifact retention and partner terms vary and can change; verify them with the provider before relying on a particular service.
Troubleshooting common headless failures
“Session not created” or ChromeDriver cannot start Chrome
First inspect the earliest driver-log error rather than changing selectors. A browser/driver major-version mismatch is a key Chrome startup failure to check. Also verify that the browser binary exists in the runtime and that the Selenium binding is using the driver you expect. Print or otherwise record the browser and driver versions in CI. If your image updates Chrome independently from a pinned ChromeDriver, align their major versions or change the version-management strategy.
Browser binary or driver is missing
Check what is installed in the local machine or container image. If no driver is supplied, Selenium Manager can discover, download and cache one when invoked by Selenium bindings, but the environment still needs the browser and a compatible driver. A missing browser binary is not repaired by changing the headless flag.
Page is blank, incomplete or still loading at assertion time
Separate startup from application timing: reproduce headfully if practical, check the first driver error, and capture a screenshot, page source and logs on failure. Replace fixed sleeps with waits for the actual page state your test needs. A successful navigation call alone does not prove that client-side rendering or the target element has finished.
Layout differs between local and CI
Compare browser versions, operating system and viewport dimensions, then run the same smoke test in headful and headless modes. A fixed viewport removes one source of variation but does not make different browser builds or runtime environments identical. Do not treat a screenshot difference by itself as proof that the selector is wrong.
Tests pass locally but time out in a container
Check the first browser or driver log error and whether the container includes the browser binary and its runtime dependencies. Use --no-sandbox only if the specific runtime requires it and your security model allows it. Preserve the container image version and failure artifacts so the issue can be compared against a known run instead of repeatedly changing test waits.
Performance, reliability and cost considerations
Headless mode removes the visible browser window; it does not make the browser, page or test framework disappear. The sources cited here do not establish a universal speedup percentage, so treat performance as something to measure in your own CI environment. Compare equivalent test runs using the same browser build, viewport, page state and workload.
Reliability usually depends more on a controlled environment and deterministic test conditions than on whether the browser is visible. Pin or record relevant versions, use explicit application-state waits, close sessions, and retain enough artifacts to identify the first failure. For remote grids, account for the fact that the browser runs on another host and verify provider-specific pricing, regions and retention separately.
Or skip the browser setup
If you need a page image or PDF rather than an interactive Selenium UI test, ScreenshotNeo is a screenshot API and MCP server for developers. It does not replace Selenium for clicking through workflows or asserting application behavior; it can take a page capture without installing and managing a browser in your test script. One Python request is:
import requests
r = requests.get(
"https://api.screenshotneo.com/v1/shot",
params={"access_key": "YOUR_API_KEY", "url": "https://example.test"},
timeout=90,
)
open("shot.webp", "wb").write(r.content)See the ScreenshotNeo API documentation for request options. Cookie banners are accepted and removed before capture, along with known consent platforms, newsletter popups and chat widgets; each step can be turned off. Bot checks, blank pages and failed loads are never billed. An MCP server lets AI agents use screenshot tools. The free plan includes 1,000 screenshots per month with no card, and paid plans start at $5 for 3,000. Sign up for the free plan.
Choosing the right approach
Use Selenium headless when the test must exercise a browser workflow: it needs to click, type, navigate, or verify behavior through WebDriver. Use Remote WebDriver when the browser should run on a separate host or a grid. Use a screenshot API for page captures when you do not need interactive UI-test assertions. These approaches solve related but different problems; a screenshot alone does not establish that a user flow works.
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.
