ScreenshotNeo

BlogHow-to

How to Configure ChromeDriver to Run Chrome in Headless Mode with Selenium

Run Chrome without a visible window in Selenium. This guide covers Python setup, browser options, version matching, CI reliability, errors, and alternatives.

By the ScreenshotNeo team30 September 20269 min read

How to Configure ChromeDriver to Run Chrome in Headless Mode with Selenium

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 current Python examples, the argument is --headless=new; Chrome documentation also shows the shorter --headless spelling. Use the spelling supported by the Chrome and Selenium versions in your environment.

from selenium import webdriver
from selenium.webdriver.chrome.options import Options

options = Options()
options.add_argument("--headless=new")

driver = webdriver.Chrome(options=options)
try:
    driver.get("https://example.com")
    print(driver.title)
finally:
    driver.quit()

This starts a Selenium session, loads https://example.com, prints the page title, and always closes Chrome. The same pattern works for navigation, DOM inspection, screenshots, PDF workflows, and test suites. The important details are that headless mode is a Chrome command-line argument, and the options object must be supplied to webdriver.Chrome.

1. What headless Chrome means

Headless mode runs Chrome without displaying its user interface on your desktop or CI worker. Since Chrome 112, unified headless uses the same Chrome implementation as regular mode; Chrome creates platform windows internally but does not show them. This gives automation access to normal browser behavior while keeping the session invisible. See the Chrome headless documentation.

Headless is useful when a test runner, scraper, scheduled job, container, or server has no display. It is also useful when you want deterministic automation without a human taking control of the browser. Headless does not make a page faster by definition, and it does not bypass authentication, bot detection, or application permissions.

Unified headless versus the standalone shell

The old, separate headless implementation is no longer the ordinary mode inside Chrome. Since Chrome 132, the legacy implementation is available as a separate chrome-headless-shell binary. Most Selenium users should use unified headless through ChromeOptions. Consider the shell only when a task specifically requires its narrower command-line behavior; it is not a replacement for a normal Selenium WebDriver session.

2. Install Selenium and prepare Chrome

Install Selenium in the Python environment that runs your script:

python -m pip install -U selenium

You need a compatible Chrome browser and a way for Selenium to locate a driver. Selenium 4 includes Selenium Manager, which can resolve browser and driver components in many setups. Selenium’s Chrome documentation advises matching the Chrome and ChromeDriver major versions, especially when a session fails to start. Record the browser, driver, Python, and Selenium versions in CI so a future image update does not become a mystery failure.

Check your browser version from Chrome’s About page or your operating system package manager. If your organization supplies a custom browser binary, configure its path explicitly. Selenium Manager documents browser path, browser version, and driver version settings in its resolution guide.

3. Minimal Python setup

Save the following as headless_title.py and run it with python headless_title.py:

Selenium passes Chrome options to a headless browser session, which can then render and save a page.
Selenium passes Chrome options to a headless browser session, which can then render and save a page.
from selenium import webdriver
from selenium.webdriver.chrome.options import Options

TARGET = "https://example.com"

options = Options()
options.add_argument("--headless=new")

driver = webdriver.Chrome(options=options)
try:
    driver.get(TARGET)
    print(f"title: {driver.title}")
finally:
    driver.quit()

The try/finally block matters. If navigation or an assertion raises an exception, quit() still releases the browser process and its temporary resources. For a long-running test suite, create one driver per isolation boundary and close it in a fixture or teardown hook.

Using the shorter argument

Chrome’s current examples use --headless. If --headless=new is rejected by an old browser or an older Selenium setup, try:

options.add_argument("--headless")

Do not treat one spelling as universal. The supported choice depends on the Chrome build and the Selenium binding. Selenium’s 2023 announcement explains that convenience headless properties were deprecated in Selenium 4.8 and removed in 4.10; explicit browser arguments are the current approach. See the Selenium announcement.

4. Practical Chrome options

Headless itself is one argument. Add other options only when your application needs them:

Option Purpose Example
Headless mode Hide the browser UI --headless=new or --headless
Window size Set the CSS viewport used by responsive layouts --window-size=1440,900
Incognito Start without the normal profile’s browsing state --incognito
Custom browser binary Use a non-default Chrome or Chromium executable options.binary_location = "/path/to/chrome"
Page logging Request browser log output for diagnostics options.set_capability("goog:loggingPrefs", {"browser": "ALL"})

Python’s Options class exposes add_argument and related configuration methods in the Selenium Python API. ChromeDriver accepts Chrome-specific arguments and capabilities through ChromeOptions; the ChromeDriver capabilities reference lists the supported structure.

Viewport and screenshots

Headless Chrome still has a viewport. Set it deliberately when a screenshot or responsive test must be reproducible:

from selenium import webdriver
from selenium.webdriver.chrome.options import Options

options = Options()
options.add_argument("--headless=new")
options.add_argument("--window-size=1365,768")

driver = webdriver.Chrome(options=options)
try:
    driver.get("https://example.com")
    driver.save_screenshot("example.png")
finally:
    driver.quit()

A window-size argument controls the initial viewport. For a particular page, you can also call driver.set_window_size(width, height) after the session starts. Full-page screenshots may require page-specific scrolling or a browser/CDP technique; headless mode alone does not guarantee that an image contains content below the viewport.

Waiting for dynamic pages

Do not rely on a fixed sleep when an element or state signals readiness. An explicit wait is clearer and usually more reliable:

from selenium.webdriver.common.by import By
from selenium.webdriver.support.ui import WebDriverWait
from selenium.webdriver.support import expected_conditions as EC

wait = WebDriverWait(driver, 20)
wait.until(EC.visibility_of_element_located((By.CSS_SELECTOR, "main")))

Choose a selector that represents usable content, and set a timeout that reflects the slowest acceptable environment. A network-idle assumption can be wrong for analytics, streaming, or long-polling applications.

5. Running in CI, containers, and servers

Headless mode removes the need for a visible display, but the worker still needs a working Chrome installation, permissions, fonts, certificates, and enough CPU and memory. Build a repeatable environment that records exact browser and driver versions. When your CI image changes, compare those versions first.

Keep the browser profile isolated. A fresh temporary profile avoids extensions, cached credentials, and preferences from a developer workstation. If you need a persistent profile, provide it intentionally and protect cookies and tokens. Do not add flags such as --no-sandbox or --disable-dev-shm-usage as universal fixes; they change security or resource behavior and were not established as required by the official setup guidance. Investigate the actual container permissions and shared-memory limits before changing them.

For parallel jobs, give each session its own profile and avoid oversubscribing CPU or memory. A browser that starts successfully in one process can fail when many sessions compete for the same worker. Capture browser and driver logs on failure, but avoid logging credentials or session cookies.

6. Common errors and fixes

“SessionNotCreatedException” or ChromeDriver cannot start Chrome

Cause: Chrome and ChromeDriver major versions do not align, or the driver points at a browser that is not installed.

Fix: Check both versions, update or pin compatible components, and rerun. Selenium’s Chrome documentation specifically calls out major-version matching.

“Unable to obtain driver” or Selenium cannot find a driver

Cause: Selenium Manager cannot resolve a driver in the current environment, or network and filesystem policy prevents resolution.

Fix: Verify Selenium Manager settings, the browser path, and any configured browser or driver version. In restricted CI, install the approved driver during image creation and make its location explicit.

Chrome binary not found

Cause: Chrome is installed outside the standard location, or only Chromium is present.

Fix: Set options.binary_location to the executable path and confirm the process user can execute it. Check the path inside the same container or VM that runs Python.

The page is blank or content is missing

Cause: The application renders asynchronously, requires a consent action, redirects to authentication, or detects automation.

Fix: Wait for a meaningful DOM condition, inspect the final URL and page source, and handle authentication in a controlled test account. Headless mode does not guarantee access to content that a normal visitor cannot access.

Different layout or screenshot dimensions

Cause: The default viewport, device scale factor, fonts, or responsive breakpoints differ between machines.

Fix: Set a window size, install the required fonts, and keep the browser version consistent. Compare computed viewport dimensions inside the page when diagnosing a mismatch.

Old code uses a removed headless property

Cause: Older Selenium examples used convenience methods or properties that were deprecated and removed.

Fix: Replace them with options.add_argument("--headless=new") or the supported --headless spelling for your Chrome version.

7. Reliability, performance, and cost considerations

Headless sessions still pay the normal browser startup cost. Reusing a driver for related operations can reduce startup overhead, while separate sessions provide stronger isolation. Keep waits targeted: a 20-second global sleep makes every fast page slow, whereas an explicit wait finishes as soon as the required state exists.

Reliability improves when browser and driver versions are pinned, viewport and locale are explicit, profiles are isolated, and failures retain the final URL, console logs, screenshot, and HTML needed for diagnosis. Use retries only for transient navigation failures; retrying deterministic selector or authentication errors increases load without fixing the cause.

Chrome itself is free to run, but your infrastructure still consumes CPU, memory, storage, and network bandwidth. Account for those resources when choosing concurrency. If you only need a rendered image or PDF and do not need browser-level interaction, a screenshot API can remove the browser lifecycle from your application.

8. Or skip the browser setup

ScreenshotNeo provides a website screenshot API and MCP server. One GET request returns a PNG, JPEG, WebP, or PDF, so you do not install ChromeDriver or maintain a browser process. See the ScreenshotNeo documentation.

A capture service can remove common consent and overlay elements before rendering the final image.
A capture service can remove common consent and overlay elements before rendering the final image.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp
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)
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' }); const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

ScreenshotNeo removes cookie and consent banners, newsletter popups, and chat widgets before capture. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed; response headers identify the page verdict and whether the request was billed. Its MCP server exposes take_screenshot, get_page_info, and capture_pdf for Claude, Cursor, and other MCP clients. You can use full-page capture, element selectors, dark mode, device presets, custom CSS and JavaScript, waits, request blocking, headers, cookies, user agent, authorization, timezone, geolocation, transparent backgrounds, resizing, caching, signed links, async webhooks, bulk capture, and usage reporting. Every feature is on every plan. The Free plan includes 1,000 screenshots per month without a card; paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account.

9. Selenium, Chrome CLI, and ScreenshotNeo: choosing an approach

Need Best fit Reason
Click buttons, inspect DOM, or run an end-to-end test Selenium headless You control a live WebDriver session and browser state.
Run a direct browser command such as a one-off capture Chrome headless CLI Chrome documents command-line screenshot, PDF, and DOM serialization tasks.
Capture many URLs without managing browsers ScreenshotNeo A hosted request supports bulk capture and handles browser setup.
Let an AI agent capture or inspect pages ScreenshotNeo MCP The MCP tools are designed for MCP clients.

10. Frequently asked questions

Can I use headless mode with Selenium 4?

Yes. Pass a Chrome options object containing the explicit headless argument when creating the driver.

Does headless mode hide automation from websites?

No. Headless changes the display mode; it is not an authentication or bot-detection bypass.

Should I use Chrome or Chromium?

Use the browser approved for your project and ensure the driver targets that executable. The compatibility and path checks are the same kind of operational concern.

Why does a headless screenshot differ from my desktop screenshot?

Viewport size, device scale, fonts, browser version, locale, and page timing can all change rendering. Set those inputs explicitly and wait for a stable page state.

Can ScreenshotNeo replace Selenium for interactive tests?

No. ScreenshotNeo is intended for screenshots, page information, PDFs, and related capture workflows. Keep Selenium when your test must click through application behavior or inspect a live session.

11. Final checklist

  • Install a supported Selenium version and confirm Chrome is available.
  • Create Options() and add the supported headless argument.
  • Pass options=options to webdriver.Chrome.
  • Match Chrome and ChromeDriver major versions.
  • Set viewport, profile, fonts, and locale when output must be reproducible.
  • Use explicit waits for dynamic content and always call driver.quit().
  • Capture diagnostics when startup or rendering fails.
  • Use ScreenshotNeo when a hosted screenshot or PDF request is simpler than maintaining ChromeDriver.