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 Chrome through ChromeDriver without showing a browser window, install Selenium, add Chrome’s --headless=new argument to a ChromeOptions object, and pass it to webdriver.Chrome(options=...). Selenium Manager is built into Selenium, so most local setups do not need a separate driver-manager package.
This guide shows a minimal working script, explains how to select a browser-and-driver setup, and covers common startup failures. If you only need a website screenshot—not an automated browser session—see the ScreenshotNeo option after the Selenium walkthrough.
What headless mode does—and what it does not do
Headless mode runs Chrome without a visible browser window. Chrome still launches, loads pages, and is controlled through WebDriver; the mode changes the browser’s presentation, not the basic Selenium workflow. Chrome describes it as a way to run the browser unattended without visible UI (Chrome Headless mode documentation).
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 →ChromeDriver is the WebDriver server that lets Selenium control Chrome. In Python, you configure Chrome-specific behavior with ChromeOptions and pass the options to the Chrome WebDriver constructor. The examples below use Selenium’s Python binding and a local Chrome installation.
#1 Best Overall
- CRISP CLARITY: This 23.8″ Philips V line monitor delivers crisp Full HD 1920x1080 visuals. Enjoy movies, shows and videos with remarkable detail
- INCREDIBLE CONTRAST: The VA panel produces brighter whites and deeper blacks. You get true-to-life images and more gradients with 16.7 million colors
- THE PERFECT VIEW: The 178/178 degree extra wide viewing angle prevents the shifting of colors when viewed from an offset angle, so you always get consistent colors
- WORK SEAMLESSLY: This sleek monitor is virtually bezel-free on three sides, so the screen looks even bigger for the viewer. This minimalistic design also allows for seamless multi-monitor setups that enhance your workflow and boost productivity
- A BETTER READING EXPERIENCE: For busy office workers, EasyRead mode provides a more paper-like experience for when viewing lengthy documents
Install Selenium and run a minimal headless script
1. Install Selenium in the Python environment you will use
Run this in the same virtual environment or Python installation that will execute your script:
python -m pip install -U seleniumRecent Selenium guidance describes Selenium Manager as the built-in driver-management path; for the ordinary local setup, you generally do not need to install a separate WebDriver manager package. See Selenium’s driver setup guidance and the Python Chrome WebDriver API.
2. Save and run this script
Make sure a Chrome browser is available in the environment. Save the following as headless_chrome.py:
Windows 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 reinstallOutdated 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 matchRank #2
- CRISP CLARITY: This 22 inch class (21.5″ viewable) Philips V line monitor delivers crisp Full HD 1920x1080 visuals. Enjoy movies, shows and videos with remarkable detail
- 100HZ FAST REFRESH RATE: 100Hz brings your favorite movies and video games to life. Stream, binge, and play effortlessly
- SMOOTH ACTION WITH ADAPTIVE-SYNC: Adaptive-Sync technology ensures fluid action sequences and rapid response time. Every frame will be rendered smoothly with crystal clarity and without stutter
- INCREDIBLE CONTRAST: The VA panel produces brighter whites and deeper blacks. You get true-to-life images and more gradients with 16.7 million colors
- THE PERFECT VIEW: The 178/178 degree extra wide viewing angle prevents the shifting of colors when viewed from an offset angle, so you always get consistent colors
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()Run it with python headless_chrome.py. If the browser and driver can start and the page loads, the script prints the page title and exits. There is no visible Chrome window in headless mode.
Why the cleanup matters
The try/finally block ensures Selenium calls driver.quit() even if navigation or later code raises an exception. Selenium’s session guidance recommends quitting the session for teardown rather than merely closing a window. Without cleanup, a driver or browser process can be left running after the script stops.
Choose how Chrome and ChromeDriver are managed
The right setup depends on whether you value convenience or reproducible runs. A browser and driver still need to be compatible; headless mode does not remove that requirement.
Rank #3
- Clear visuals. Fluid motion: A 144Hz refresh rate and 1ms MPRT deliver smooth, tear‑free motion across work, gaming, and streaming for clearer, more fluid viewing.
- Eye comfort: TÜV Rheinland 3‑star* certification reduces harmful blue light while preserving stunning color quality without compromise. *TÜV Rheinland 3-star eye comfort certification.
- Wide viewing angle: Get consistent views across a wide 178° /178° viewing angle.
- In-Plane Switching (IPS): See excellent color accuracy and consistency across wide viewing angles with In-plane Switching (IPS) technology.
- Ultra-thin bezels: Maximize your viewing experience with thin bezels.
| Setup | When it fits | What to know |
|---|---|---|
| Installed Chrome with Selenium Manager | Local development and straightforward scripts | Selenium Manager is built into Selenium and is the standard automatic driver-management path described in Selenium’s guidance. It may need to obtain a suitable driver, so the environment must permit the required downloads. |
| Version-pinned Chrome for Testing browser and driver | CI or other runs where repeatability matters | Chrome and ChromeDriver releases are integrated through Chrome for Testing for Chrome 115 and later. Pin a matching pair to make the browser version used by the run explicit. See Chrome automation and testing. |
| Custom ChromeDriver executable via Selenium Service | Managed environments that specify a driver path or custom service setup | Pass the service configuration using service=. Keep browser settings such as headless mode in options=; these are separate constructor inputs in Selenium’s Python API. |
For reproducible CI: pin a matching pair
Chrome’s automation documentation points to version-pinned Chrome for Testing downloads as a way to keep automated tests deterministic. For Chrome 115 and later, use the Chrome for Testing version-selection resources to obtain aligned browser and driver releases. If you are using a non-Chrome-for-Testing Chrome binary, Chrome documents selecting a driver by the browser’s MAJOR.MINOR.BUILD version, with a milestone fallback when needed. Follow the current ChromeDriver version-selection guidance rather than assuming one driver version works with every Chrome release.
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Clear out junk files and repair common Windows errors3Fix the driver behind crashes, sound loss and screen glitchesExact current release numbers depend on the machine and release channel, so there is no single version pair that is right for all readers. Record the browser and driver versions used by your CI job when diagnosing a failure.
For a custom executable: use the Service parameter
If your environment already provides a ChromeDriver executable, pass its path through Selenium’s Chrome service object and continue to pass browser arguments through options:
Rank #4
- CURVED FOR ENHANCED ENGAGEMENT: An immersive viewing experience with a curved monitor that wraps more closely around your field of vision; It creates a wider view, enhancing depth perception and minimizing peripheral distraction
- SMOOTH PERFORMANCE FOR SEAMLESS CONTENT: Stay in the action when playing games, watching videos, or working on creative projects; The 100Hz refresh rate reduces lag and motion blur so you don't miss a thing in fast-paced moments¹
- MORE GAMING POWER: Gain the edge with optimizable game settings; Color and image contrast can be adjusted to see scenes more vividly and spot enemies hiding in the dark; Game Mode adjusts any game to fill the screen so you can view every detail²
- KEEP IT EASY ON THE EYES: Care for your eyes and stay comfortable, even during long sessions; Advanced eye comfort technology certified by TÜV reduces eye strain by minimizing blue light and reducing irritating screen flicker²
- INCREASED VERSATILITY: Connect to more; Plug devices straight into your monitor for increased flexibility, making your computing environment even more convenient
from selenium import webdriver
from selenium.webdriver.chrome.service import Service
options = webdriver.ChromeOptions()
options.add_argument("--headless=new")
service = Service(executable_path="/path/to/chromedriver")
driver = webdriver.Chrome(service=service, options=options)
try:
driver.get("https://example.com")
print(driver.title)
finally:
driver.quit()Replace /path/to/chromedriver with the actual executable path for your system. This example assumes you have selected a driver compatible with the Chrome binary being launched; a custom path does not resolve a version mismatch by itself.
Use the current Chrome Headless option
For a new Selenium script, use --headless=new to state explicitly that you want Chrome’s unified headless mode. Current Chrome also accepts --headless. The two spellings select headless operation; the explicit form makes the intended mode clear in scripts and configuration.
Free tools Windows power users keep installed
One-click scans. No signup required.
Do not build a new setup around --headless=old. Chrome 132 removed the old headless implementation from the regular Chrome binary. If a project specifically depends on that older implementation, Chrome distributes it separately as chrome-headless-shell; otherwise use unified headless mode. See Chrome’s notice on removing --headless=old from Chrome and its Headless mode documentation. Selenium also discussed the transition in its 2023 headless announcement.
Best Value
- 【INTEGRATED SPEAKERS】Whether you're at work or in the midst of an intense gaming session, our built-in speakers provide rich and seamless audio, all while keeping your desk clutter-free.
- 【EASY ON THE EYES】 Protect your eyes and enhance your comfort with Blue-Light Shift technology. This feature reduces harmful blue light emissions from your screen, helping to alleviate eye strain during long hours of use and promoting healthier viewing habits.
- 【WIDEN YOUR PERSPECTIVE】Our sleek minimal bezel design ensures undivided attention. The nearly bezel-free display seamlessly connects in a dual monitor arrangement, delivering an unobstructed view that lets you focus on more at once, completely distraction-free.
Common ChromeDriver headless errors and fixes
| Symptom | Likely cause | What to check or do |
|---|---|---|
NoSuchDriverException or driver startup failure |
Selenium is missing from the active Python environment, driver management could not obtain a driver, or a custom service path is wrong. | Install Selenium with python -m pip install -U selenium using the interpreter that runs the script. If using Service, verify its executable path. If Selenium Manager needs to download a driver, check that the environment can reach the required downloads. |
| Browser/driver version mismatch | The selected ChromeDriver is not compatible with the Chrome binary. | Check the installed Chrome version, then select its matching driver using Chrome’s version-selection procedure. For Chrome 115 and later, use a matching Chrome for Testing browser/driver pair when practical. |
| No browser window appears | This is expected when headless mode is enabled. | Check the script’s result, logs, or captured output rather than expecting a visible Chrome window. Headless mode is specifically for unattended use without visible UI. |
--headless=old no longer starts the expected implementation |
The legacy implementation was removed from the regular Chrome binary beginning with Chrome 132. | Use --headless=new or --headless for unified Chrome Headless. Use the separately distributed chrome-headless-shell only if the older implementation is a specific requirement. |
| A driver or browser process remains after an error | The session did not reach its teardown code. | Put browser work inside a try block and call driver.quit() in finally, as in the minimal example. |
Avoid adding flags such as --no-sandbox as a blanket repair. The setup guidance cited here does not establish that flag as necessary for every machine. First diagnose the specific container, permission, or browser error; change security-related settings only when the environment’s requirements call for it.
Improve repeatability and diagnose failures efficiently
- Keep environment boundaries clear. Install Selenium and run the script with the same Python interpreter or activated virtual environment.
- Make browser versions deliberate in CI. Pin a Chrome for Testing browser/driver pair when reproducible automation is more important than automatically following the installed browser.
- Separate browser options from service configuration. Put Chrome arguments in
ChromeOptions; useservice=for a custom ChromeDriver service or executable. - Clean up every session. Use
driver.quit()in afinallyblock so cleanup still occurs after a navigation or assertion failure. - Change one variable at a time. If startup fails, first confirm Selenium installation and the driver path or automatic download, then verify browser/driver compatibility, and only then investigate environment-specific permissions.
ChromeDriver’s role and platform availability are described in Chrome’s ChromeDriver documentation. The actual Chrome, ChromeDriver, and Selenium versions are environment-dependent; check the versions used by the failing run rather than relying on an example from a different machine.
Or skip the browser setup
If your goal is simply to save a website screenshot or PDF, rather than interact with a browser using Selenium, ScreenshotNeo is a website screenshot API and MCP server. It is not a replacement for WebDriver-based browser automation when you need to click through a workflow, inspect live DOM state, or run application tests. For a capture task, the API accepts one GET request with a URL and returns an image or PDF.
Here is the Python call for a WebP screenshot:
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)See the ScreenshotNeo documentation for API options and response details. The same request in cURL and Node.js is:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpconst q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);ScreenshotNeo can accept cookie or consent banners and remove more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each of those steps can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers indicate the page verdict and billing status. Its MCP server exposes take_screenshot, get_page_info, and capture_pdf for Claude, Cursor, and other MCP clients. The free plan includes 1,000 shots a month with no card; paid plans start at $5 for 3,000 shots. Every feature is available on every plan.
Sign up for ScreenshotNeo’s free plan to try screenshot capture without a card.
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.
