The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
Use Selenium 4’s Chrome options to start Chrome in headless mode: add --headless=new, then pass the options to webdriver.Chrome(options=options). Headless Chrome runs without displaying a browser window; it is still a real browser session that can navigate and interact with pages. Close it with driver.quit() in a finally block so the session is cleaned up if the script fails.
Start Chrome headlessly with Python
Install Selenium in the same Python environment that will run your script:
python -m pip install seleniumThen save this as, for example, headless_chrome.py and run it with Python. The sample opens a page, prints its title, and always attempts to close the browser session.
from selenium import webdriver
options = webdriver.ChromeOptions()
options.add_argument("--headless=new")
# Optional: set a predictable viewport for screenshots or responsive layouts.
options.add_argument("--window-size=1440,1000")
driver = webdriver.Chrome(options=options)
try:
driver.get("https://example.com")
print(driver.title)
finally:
driver.quit()The key setting is --headless=new. The window-size argument is optional: include it when the page’s responsive layout or a screenshot needs a known viewport, and omit it if the default viewport is suitable. In current Selenium Python, configure Chrome through webdriver.ChromeOptions() and pass the resulting object as options=.
#1 Best Overall
What background or headless mode does—and does not do
Headless mode starts Chrome without a normal visible browser window. It does not turn Selenium into a lightweight HTML parser: Chrome still has to start, load the site, execute page code, and perform the requested interactions. Nor does the headless flag install Chrome, provide missing operating-system libraries, or make asynchronous page content ready sooner.
Use headless mode when a script or CI job should run without a desktop window. If you need to watch a failure as it happens, temporarily remove the headless argument and run with a display available; this makes the browser visible for diagnosis, but changes the execution mode from the final background run.
Configure Chrome options for the task
Choose whether to set a viewport
--window-size=1440,1000 asks Chromium for a particular window size. It is useful for repeatable screenshots and for testing a specific responsive breakpoint. It is not required for headless operation. If your goal is to test mobile or tablet behavior, choose a viewport appropriate to that case rather than assuming a desktop-sized window represents it.
Keep options purposeful
Chrome accepts command-line arguments through options.add_argument(...). Keep the basic configuration small and add arguments only to solve a concrete environment or test requirement. In particular, do not copy --no-sandbox from snippets as a routine headless setting. It is not required by the basic workflow, and changing sandbox behavior has security implications; use it only when the environment specifically requires it and you understand the trade-off.
For a custom Chrome installation, Selenium’s Chrome options support selecting an alternate browser binary. Most scripts should leave the binary unset and let Selenium find Chrome or use Selenium Manager’s browser-management capabilities where supported.
Let Selenium Manager resolve the driver—or pin one yourself
Default: let Selenium Manager manage the driver
Selenium Manager is shipped with Selenium and is invoked by the language bindings when a driver is not otherwise available. For a basic script, this often removes the need to install ChromeDriver separately: Selenium Manager can discover, download, and cache a suitable driver. It can also manage Chrome browser downloads in supported configurations.
The first resolution may require network access. A proxy, offline build worker, custom browser installation, restricted network policy, or requirement to pin a browser version can require extra configuration. Selenium Manager supports configuration through command-line arguments, a se-config.toml file, and environment variables, including browser-version selection. If your environment deliberately fixes browser versions, configure that policy rather than relying on a download that the worker cannot perform.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Manual driver: use Service
If you manage a ChromeDriver executable yourself, pass it with Selenium 4’s Service object. The former executable_path constructor argument is not the current approach.
from selenium import webdriver
from selenium.webdriver.chrome.service import Service
options = webdriver.ChromeOptions()
options.add_argument("--headless=new")
service = Service("/path/to/chromedriver")
driver = webdriver.Chrome(service=service, options=options)
try:
driver.get("https://example.com")
print(driver.title)
finally:
driver.quit()Chrome and ChromeDriver need compatible versions; the Chrome documentation specifies matching major versions. If Chrome updates while a manually installed driver stays behind, check both versions. Either supply a compatible driver through Service or remove the stale driver from the setup and let Selenium Manager resolve it. Forcing an unmatched ChromeDriver build is unsupported.
Wait for the page state you actually need
A successful call to driver.get() does not mean every application-level element or piece of dynamic content is ready. JavaScript may render content after navigation returns. Before interacting with an element, wait for that element or another meaningful page condition rather than assuming a fixed sleep will always be enough.
For example, use an explicit wait for a result that must be visible:
from selenium import webdriver
from selenium.webdriver.common.by import By
from selenium.webdriver.support import expected_conditions as EC
from selenium.webdriver.support.ui import WebDriverWait
options = webdriver.ChromeOptions()
options.add_argument("--headless=new")
driver = webdriver.Chrome(options=options)
try:
driver.get("https://example.com")
heading = WebDriverWait(driver, 10).until(
EC.visibility_of_element_located((By.TAG_NAME, "h1"))
)
print(heading.text)
finally:
driver.quit()The 10-second value here is the maximum time this particular wait will look for the condition; it is not a guarantee that every page becomes ready within that time. Choose a timeout that fits your application and handle a timeout as a meaningful test failure or recovery case.
Selenium’s default page-load strategy, normal, waits for the load event. The eager strategy returns at DOMContentLoaded, and none waits only for the initial page download. Faster strategies shift more responsibility to your script: use them only when your subsequent waits reliably identify the state needed before interaction. An earlier return by itself does not make a test reliable or prove that the page is usable.
Run headless Chrome in CI or a Linux container
In a container or CI worker, check the runtime rather than treating the headless flag as a deployment fix. Chrome must be installed in the image, or a supported Selenium Manager configuration must be able to download it. Required system libraries and network access must also be available. The required libraries differ by Linux distribution and image, so use the browser/runtime requirements for the specific base image rather than copying an assumed universal dependency list.
- Confirm which Python environment runs the job and that Selenium was installed into that environment.
- Confirm Chrome is present, or that the worker can reach the browser download source used by the configured manager.
- Check outbound network and proxy rules if Selenium Manager cannot resolve or download a driver or browser.
- If you pin Chrome or ChromeDriver, verify their major versions are compatible.
- Make sure your script reaches its cleanup path and calls
driver.quit().
Troubleshoot common failures
| Symptom | Likely cause | What to check or change |
|---|---|---|
| Chrome fails to start | Chrome is missing, the worker cannot download it, or the runtime lacks required dependencies. | Confirm the installed browser or Selenium Manager configuration, network access, and the dependencies for the actual container image. |
| “This version of ChromeDriver only supports Chrome version …” | The browser and manually selected driver are incompatible. | Check their major versions. Use a matching executable with Service or remove the stale driver and let Selenium Manager resolve one. |
| A browser window appears | The headless argument was omitted, misspelled, or not passed to the driver. | Verify the options passed to webdriver.Chrome include options.add_argument("--headless=new"). Do not rely on the removed options.headless = True form. |
| Chrome processes remain after the script | The WebDriver session was not quit, often because an exception bypassed cleanup. | Put work inside try and call driver.quit() from finally. |
| An element is intermittently missing | The page’s application code has not rendered the expected state yet. | Wait for the expected element or state before using it; do not treat navigation completion as proof that dynamic content is ready. |
| Selenium Manager cannot resolve a driver | Network or proxy restrictions, an offline worker, custom browser location, or a stale manually installed driver may be involved. | Check network policy and browser paths, review Selenium Manager configuration, or provide a compatible driver through Service. |
Or skip the browser setup
If your task is simply to save a website screenshot or PDF—not to test interactions or automate a browser workflow—a screenshot API can handle the capture without a local Selenium and Chrome setup. ScreenshotNeo is a website screenshot API and MCP server for developers; it accepts one GET request with a URL and returns an image or PDF. The API supports PNG, JPEG, and WebP output as well as PDF capture. See the ScreenshotNeo API documentation for request options.
Free tools Windows power users keep installed
One-click scans. No signup required.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com -o shot.webpScreenshotNeo accepts cookie or 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 turned off. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and the response reports the page verdict and billing status in X-Page-Verdict and X-Billed headers. An MCP server provides take_screenshot, get_page_info, and capture_pdf tools for AI agents, including Claude, Cursor, and other MCP clients.
The Free plan includes 1,000 screenshots a month with no card. Paid plans start at $5 for 3,000 shots; every feature is available on every plan, and yearly billing gives two months free. Those captures are not a replacement for Selenium when you need to click through a workflow, assert application behavior, or test interactive states. For screenshot-only work, start at ScreenshotNeo and sign up for 1,000 free screenshots a month with no card.
Frequently asked questions
Does headless Chrome need a desktop session?
No normal browser window is displayed in headless mode. The browser still needs a usable runtime and its required dependencies; headless mode does not supply them.
Can I use Selenium headless mode to test clicks and forms?
Yes. Headless mode changes whether Chrome displays a window, not the purpose of WebDriver. You can automate interactions as usual, provided the page has reached the state your test expects.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Should I add --no-sandbox?
Not by default. The basic headless setup does not require it. Add it only if your runtime specifically calls for it and you have considered the security trade-off.
When is a screenshot API a better fit than Selenium?
Use one when the deliverable is a page image or PDF and you do not need to automate or verify interactive behavior. Selenium remains the fit for browser-driven actions and tests.
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.
