To run Chrome without a visible browser window in Selenium, add Chrome’s --headless startup argument to a Chrome options object and pass that object when creating the WebDriver session. In Python, the current setup looks like this:
Configure ChromeDriver for headless Chrome in Python
Headless mode runs Chrome without displaying its user interface. Since Chrome 112, headless and regular Chrome share the same browser implementation: Chrome creates platform windows but does not show them. For most Selenium tasks, use this unified mode rather than the separate legacy headless shell. Chrome’s headless documentation describes the transition.
Here is a complete Python example. Install Selenium first with python -m pip install selenium, then save the script and run it in an environment where Chrome is installed and available to Selenium.
from selenium import webdriver
from selenium.webdriver.chrome.options import Options
options = Options()
options.add_argument("--headless")
driver = webdriver.Chrome(options=options)
try:
driver.get("https://example.com")
print(driver.title)
finally:
driver.quit()The script should print the page title and close the WebDriver session even if navigation or printing raises an error. The finally block matters in longer-running scripts and test suites: it ensures the browser process is asked to exit rather than being left open after a failure.
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →#1 Best Overall
What each configuration line does
Options()creates the Chrome-specific options object in Selenium’s Python binding.add_argument("--headless")adds a Chrome startup argument requesting headless mode.webdriver.Chrome(options=options)starts a session with those options. ChromeDriver accepts Chrome-specific arguments through ChromeOptions; see ChromeDriver capabilities.driver.get(...)navigates to the URL, anddriver.titlereads the resulting document title.driver.quit()ends the session and releases its browser resources.
Selenium’s Python API documents the Chrome Options class and its add_argument method in the Selenium 4.49.0 Python API reference. Selenium’s broader Chrome WebDriver documentation also lists --headless=new among commonly used Chrome arguments. The flag spelling can depend on the Chrome environment: Chrome’s current headless examples use --headless, while Selenium documents the explicit --headless=new form. If one is not recognized in your setup, try the other and keep the one supported by your installed Chrome.
How to adapt the example to your Selenium binding
The configuration idea is the same across bindings: add a Chrome command-line argument to that binding’s Chrome options object, then pass the options when constructing the driver. The code syntax is not universal; use the documentation for your specific binding. The Python example above is the directly documented binding example here.
Do not copy Python’s Options class or keyword argument syntax into Java, JavaScript, or another language. Find that language’s Selenium Chrome options API, add the headless argument using its documented method, and supply the resulting options to its Chrome driver constructor.
Choose the right headless implementation
Unified headless Chrome
Use Chrome’s ordinary --headless mode for typical Selenium automation. Since Chrome 112, headless uses the same Chrome implementation as regular mode while suppressing the visible interface. This is the normal choice when you want Selenium to navigate, inspect pages, or interact with web content without opening a visible browser window. Chrome for Developers documents this unified implementation.
Rank #2
The legacy headless shell
The older, separate headless implementation is no longer the ordinary headless mode built into Chrome. Since Chrome 132, it is available as the standalone chrome-headless-shell binary. Most Selenium users should not seek it out for a routine headless session; consider it only when a task specifically depends on that separate shell. Consult Chrome’s documentation for its availability and distinction from unified headless.
Selenium versus Chrome’s command-line interface
Headless Chrome can also perform direct command-line tasks, including screenshot capture, PDF output, and DOM serialization. Those are Chrome CLI workflows, not Selenium WebDriver code. If you need WebDriver features such as locating elements or interacting with a page, configure the browser through Selenium as shown above. For command-line-only operations, see Chrome’s headless command-line reference.
Check Chrome, ChromeDriver, and Selenium compatibility
Selenium’s Chrome documentation describes Chrome 75 and later as compatible with Selenium 4 and advises matching the Chrome and ChromeDriver major versions. When a session fails at startup, check that version relationship before changing headless flags or adding unrelated arguments. See Selenium’s Chrome documentation for its compatibility guidance.
For repeatable local runs and CI jobs, record the Selenium, Chrome, and driver versions used by the job. Pinning and recording these dependencies helps distinguish a code change from a browser update when a previously working session stops starting or behaves differently. Do not assume that a particular version is the latest without checking the versions available in your environment.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minutePC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Use Selenium Manager when browser or driver discovery fails
Recent Selenium setups can use Selenium Manager to resolve browser and driver binaries. If Selenium cannot find Chrome or ChromeDriver, inspect how the browser is installed and whether the configured paths or version settings point to the intended binaries. Selenium Manager documents settings for browser path, browser version, and driver version in its official documentation.
In a managed CI environment, a browser may be installed outside the location Selenium discovers automatically. Set or correct the documented browser-path setting for that environment, and verify that any requested browser and driver versions are available and compatible. The exact configuration depends on how your CI image and Selenium Manager are provisioned.
Troubleshoot common headless startup problems
ChromeDriver reports a version or session-creation error
Compare the major version of installed Chrome with the ChromeDriver major version. Selenium advises matching these majors. Correct the mismatched installation or Selenium Manager version resolution, then retry with the same minimal Python example before adding other options.
Selenium cannot locate Chrome or ChromeDriver
Check whether Chrome is installed in the environment running the script and whether Selenium Manager is resolving the intended browser and driver. For a nonstandard browser location, review its documented browser-path setting. In CI, make sure the path and versions apply to the job container or machine that actually runs Python, not only to the host configuration.
The browser starts visibly
Confirm that the argument is added to the Chrome options object before calling webdriver.Chrome, and that the same object is passed to the constructor. If the installed Chrome does not respond to --headless, try the --headless=new spelling documented by Selenium. Avoid assuming an option applied if the session was created using a different options object.
The page is blank, incomplete, or still loading
Headless mode removes the visible UI; it does not guarantee that a page’s application has finished rendering when navigation returns. If your script needs a specific result, wait for that page condition using Selenium’s supported wait APIs rather than relying on a fixed assumption about load time. Inspect the target URL, browser logs, and page state to separate a site or network failure from a headless configuration issue.
Do not add container flags as universal fixes
Arguments such as --no-sandbox and --disable-dev-shm-usage are not required by the documented setup above. Do not add them automatically: their appropriateness depends on the runtime environment, and disabling browser sandboxing changes a security boundary. Investigate a specific sandbox or shared-memory error in the context of your container or CI image and apply only a fix justified for that environment.
Performance, reliability, and operational notes
Headless mode is a way to run Chrome without a displayed interface, not a promise that every site will load faster or render identically in every environment. Chrome’s unified mode shares the Chrome implementation with regular mode, but network conditions, page scripts, available fonts, browser versions, and machine resources can still affect a Selenium job.
Recommended Free Tools
For reliable automation, keep the browser and driver versions controlled, wait for the page state your task actually needs, and always close the driver. In parallel test runs, account for the resource use of multiple Chrome sessions and ensure each session has a cleanup path. Do not treat a timeout, blank document, or blocked page as proof that the headless argument itself failed.
Or skip the browser setup
If your goal is simply to save a web page as an image or PDF, ScreenshotNeo is a website screenshot API and MCP server for developers. Its one-call GET API can return a PNG, JPEG, WebP, or PDF. It accepts cookie and consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each of those steps can be disabled. Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers indicate the page verdict and billing status. AI agents can use its MCP server tools, including take_screenshot, get_page_info, and capture_pdf.
Example with cURL:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com -o shot.webpSee the ScreenshotNeo API documentation for setup and options. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 screenshots. Sign up for ScreenshotNeo’s free plan.
Frequently Asked Questions
Does headless mode mean Chrome is not running?
No. Chrome runs without displaying its browser interface; Selenium can still navigate pages and use WebDriver commands.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Can I use headless mode with ChromeDriver and Selenium 4?
Yes. Selenium documents Chrome 75 and later as compatible with Selenium 4, with Chrome and ChromeDriver major versions matched.
Is the Chrome headless shell the same as –headless?
No. Unified headless is Chrome’s ordinary mode; the legacy implementation is a separate chrome-headless-shell binary since Chrome 132.
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.
