How to Use Headless Chrome with Selenium for Automated Testing

To use Headless Chrome with Selenium, configure ChromeOptions by adding the --headless argument and pass it to the Chrome WebDriver. This runs Chrome without opening a visible window, useful for automated tests on servers or CI pipelines.

Syntax

Use ChromeOptions to set browser arguments. Add --headless to run Chrome without UI. Then create a webdriver.Chrome instance with these options.

• ChromeOptions(): Create options object.
• add_argument('--headless'): Enable headless mode.
• webdriver.Chrome(options=options): Start Chrome with options.

python

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

options = Options()
options.add_argument('--headless')

service = Service()
driver = webdriver.Chrome(service=service, options=options)

# Use driver as usual

# driver.get('https://example.com')

# driver.quit()

Example

This example opens the Google homepage in headless mode, prints the page title, and closes the browser. It shows how to set up and use headless Chrome with Selenium in Python.

python

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

options = Options()
options.add_argument('--headless')
options.add_argument('--disable-gpu')  # Recommended for Windows

service = Service()
driver = webdriver.Chrome(service=service, options=options)

driver.get('https://www.google.com')
print(driver.title)  # Should print 'Google'

driver.quit()

Output

Google

Common Pitfalls

Common mistakes when using headless Chrome with Selenium include:

• Not adding --headless argument, so browser opens visibly.
• Missing --disable-gpu on Windows, which can cause errors.
• Not specifying the correct path to ChromeDriver or not matching ChromeDriver version with Chrome browser.
• Trying to interact with elements before the page fully loads.

Always quit the driver to free resources.

python

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

# Wrong: Missing headless argument
options_wrong = Options()
# options_wrong.add_argument('--headless')  # Missing this causes visible browser

# Right: Add headless and disable-gpu
options_right = Options()
options_right.add_argument('--headless')
options_right.add_argument('--disable-gpu')

Quick Reference

Option	Description
--headless	Run Chrome without UI (invisible browser)
--disable-gpu	Disable GPU hardware acceleration (needed on Windows)
--window-size=width,height	Set browser window size in headless mode
--no-sandbox	Disable sandbox for Linux environments (use with caution)
--remote-debugging-port=9222	Enable remote debugging if needed

Key Takeaways

Add '--headless' argument in ChromeOptions to run Chrome without UI.

Include '--disable-gpu' on Windows to avoid errors in headless mode.

Always match ChromeDriver version with your installed Chrome browser.

Quit the WebDriver after tests to release resources.

Use waits to ensure page elements load before interacting.