How to Use Headless Browser with Selenium in Python

To use a headless browser with Selenium in Python, configure browser options to run without a GUI by adding the --headless argument. For example, with Chrome, use Options() to add --headless before creating the WebDriver instance.

Syntax

To run Selenium in headless mode, you create browser-specific options and add the --headless argument. Then, pass these options when initializing the WebDriver.

• Options(): Create browser options object.
• add_argument('--headless'): Enables headless mode.
• WebDriver(options=options): Starts browser with these options.

python

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

options = Options()
options.add_argument('--headless')
driver = webdriver.Chrome(options=options)

# Use driver as usual

# Quit when done
driver.quit()

Example

This example opens a headless Chrome browser, navigates to example.com, prints the page title, and then closes the browser. It shows how to run Selenium without opening a visible browser window.

python

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

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

with webdriver.Chrome(options=options) as driver:
    driver.get('https://example.com')
    print(driver.title)

Output

Example Domain

Common Pitfalls

Common mistakes when using headless mode include:

• Not adding --headless argument, so browser opens normally.
• Missing other recommended flags like --disable-gpu on Windows, which can cause errors.
• Assuming headless mode behaves exactly like headed mode; some UI elements may load differently.
• Not closing the driver properly, causing resource leaks.

Always test your scripts in both headed and headless modes to catch differences.

python

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

# Wrong: missing headless argument
options_wrong = Options()
# options_wrong.add_argument('--headless')  # Forgot this

# Right: add headless argument
options_right = Options()
options_right.add_argument('--headless=new')
options_right.add_argument('--disable-gpu')

# Use options_right when creating driver

Quick Reference

Step	Description	Example Code Snippet
1	Import Selenium and Options	from selenium import webdriver from selenium.webdriver.chrome.options import Options
2	Create Options and add headless	options = Options() options.add_argument('--headless=new')
3	Create WebDriver with options	driver = webdriver.Chrome(options=options)
4	Use driver as usual	driver.get('https://example.com')
5	Close driver	driver.quit()

Key Takeaways

Add '--headless' argument to browser options to run Selenium without opening a browser window.

Include '--disable-gpu' on Windows to avoid common headless mode issues.

Test your scripts in both headed and headless modes to ensure consistent behavior.

Always close the WebDriver to free system resources.

Headless mode speeds up tests by removing the UI but may behave slightly differently.