Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
“Error: no display specified” means Selenium started a headed Linux browser without access to an X11 display. This is common on CI workers, SSH sessions, Docker containers and Selenium Grid nodes. Use the browser’s native headless mode when you do not need a visible window. If the test must run headed—for example, for visual workflows or a video recorder—run it inside Xvfb and export the display it provides. If a desktop session already exists, fix the DISPLAY value and Xauthority permissions instead.
What the error means
Firefox and Chrome normally create a graphical window. On a Linux machine, that window is backed by an X server. The browser process discovers the server through the DISPLAY environment variable and authenticates with it through Xauthority data. A CI agent, container, SSH shell or Grid node often has neither a physical desktop nor a running virtual display. Starting a headed browser in that environment produces “Error: no display specified.”
Setting DISPLAY to an arbitrary value does not create an X server. The value is usable only when an X server is listening on that display and the Selenium user is authorized to connect. In Grid deployments, the browser starts on the node, so checks made only on the client or hub can be misleading.
Choose the right fix
| Situation | Recommended approach | Trade-off |
|---|---|---|
| No visible window is required | Native browser headless mode | Usually the simplest CI and container setup; rendering can differ from a headed desktop. |
| The test needs a headed browser, screenshots of a real window or a video tool that expects X11 | Xvfb (X virtual framebuffer) | Preserves headed behavior but adds X11 startup and authentication to maintain. |
| A real Linux desktop is already running | Use its valid DISPLAY and Xauthority permissions |
Depends on that session remaining available to the Selenium process. |
| Browsers run on separate machines or in parallel | Selenium Grid | Centralizes remote execution but requires node registration, capacity and network security. |
Fix 1: run Firefox or Chrome in native headless mode
Headless mode avoids the X11 window entirely. It is the first choice for ordinary functional tests, scraping jobs and CI checks where no person needs to see the browser.
#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
Firefox with Python
Selenium’s Firefox examples use the -headless argument. Selenium 4 requires Firefox 78 or newer; use a current geckodriver compatible with the installed browser, or let Selenium Manager resolve the driver when that is supported in your environment.
from selenium import webdriver
options = webdriver.FirefoxOptions()
options.add_argument("-headless")
driver = webdriver.Firefox(options=options)
try:
driver.get("https://example.com")
print(driver.title)
finally:
driver.quit()Put driver.quit() in a finally block so a failed assertion does not leave a browser process consuming the CI worker. If Firefox itself is missing, or the driver cannot resolve the binary, you will see a browser/driver error rather than a display error; install both on the machine that actually launches the browser.
Chrome with JavaScript
For current Chrome, Selenium’s documentation shows the newer headless implementation through --headless=new.
const {Builder, Browser} = require('selenium-webdriver');
const chrome = require('selenium-webdriver/chrome');
const options = new chrome.Options().addArguments('--headless=new');
const driver = await new Builder()
.forBrowser(Browser.CHROME)
.setChromeOptions(options)
.build();
try {
await driver.get('https://example.com');
console.log(await driver.getTitle());
} finally {
await driver.quit();
}Run this code with the same user and environment used by your pipeline. A local terminal may have a browser on its PATH while the Jenkins service account or container does not.
Rank #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
When headless output is not identical to headed output
- Use headed mode with Xvfb when your acceptance criterion depends on a visible window, desktop integrations or a capture tool that cannot attach to native headless Chrome or Firefox.
- For ordinary DOM assertions, headless mode removes an entire class of X11 failures and is easier to reproduce in containers.
- Record browser, driver and Selenium versions in CI logs. Compatibility changes over time, and a version change can look like a display regression.
Fix 2: run a headed browser inside Xvfb
Xvfb supplies an in-memory X server. The browser remains headed from its own perspective, but no physical monitor is needed. Install the Xvfb package supplied by your Linux distribution, then start it before Selenium.
Use the wrapper form
The simplest pattern is to make Xvfb the parent environment of the test command:
xvfb-run --server-args="-screen 0 1920x1080x24" pytestReplace pytest with your runner. The screen size and color depth are examples; choose values that match your visual assertions and the resources available on the worker. The wrapper exports a valid display for the child process and tears it down when the command exits.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Start and export a display yourself
Xvfb :99 -screen 0 1920x1080x24 &
XVFB_PID=$!
export DISPLAY=:99
# Start Selenium tests as a child of this shell.
pytest
kill "$XVFB_PID"In production scripts, use a cleanup trap so Xvfb is stopped on test failure as well as success. Display number :99 is only an example. If another process already owns it, choose a free number. The important detail is that the X server must still be alive for the entire browser lifetime and that the Selenium process inherits the same DISPLAY.
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.
Container and CI checks
- Install Xvfb in the image or worker that launches the browser, not only on a controller machine.
- Run
echo "$DISPLAY"immediately before the test and log it. - Confirm the Xvfb process is running and that the display number in the environment matches the one it opened.
- Use the same Unix user for Xvfb and Selenium where possible. If users differ, configure Xauthority deliberately rather than disabling authentication.
- Keep the virtual display alive until every browser session has quit.
Fix 3: connect to an existing desktop display
If the host really has a desktop session, inspect the environment of the process that launches the browser:
echo "$DISPLAY"
whoamiA valid value commonly resembles :0, but the number is host-specific. Verify that an X server is listening on that display and that the Selenium account can authenticate with the session’s Xauthority credentials. An SSH shell can have an empty or unrelated DISPLAY even while another user is logged into the machine. Exporting the desktop user’s value without the matching authorization will still fail.
For a remote Grid session, perform these checks on the node where Firefox or Chrome starts. The client’s display variable has no effect on a browser running elsewhere.
Fix 4: use Selenium Grid for remote or parallel browsers
Grid is appropriate when browsers must run on multiple machines, operating systems or isolated workers. Selenium’s official quick start lists Java 11 or newer, the Selenium Server JAR, browsers and their drivers as prerequisites. Standalone mode starts with:
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
java -jar selenium-server-<version>.jar standaloneThe standalone server accepts RemoteWebDriver requests on port 4444. A node still needs a valid display strategy: configure native headless mode for display-free execution, or start Xvfb on that node for headed tests. Registering a node does not manufacture an X server.
Grid validation
- Check that the node is registered and advertises the browser and capabilities your client requests.
- Verify browser and driver binaries on the node, not just on the machine sending the WebDriver command.
- Inspect the node’s
DISPLAY, Xvfb lifetime and Xauthority permissions. - Use small, isolated nodes when possible. Selenium’s Grid guidance presents roughly one CPU and about 1 GB of RAM per browser session as an operational recommendation, not a universal measurement or guarantee.
- Protect port 4444 and any Grid endpoint with firewall controls. An exposed Grid can provide access to internal applications and allow execution of custom binaries.
A repeatable diagnosis checklist
- Identify where the browser process starts: local worker, container or Grid node.
- Decide whether a visible window is actually required. If not, add the browser’s native headless flag.
- If headed execution is required, start Xvfb or connect to a real desktop display before creating the WebDriver.
- Log
DISPLAY, the Unix user, browser version, driver version and Selenium version. - Confirm the browser binary and driver are installed on the launching machine and that Selenium Manager or your configured driver path resolves the intended driver.
- Run a minimal navigation such as
https://example.combefore adding your full test suite. This separates display startup problems from application failures. - After the test, call
quit()and verify that orphaned browser, driver or Xvfb processes are not accumulating.
Common symptoms and fixes
| Symptom | Likely cause | Fix |
|---|---|---|
Error: no display specified immediately at startup |
Headed browser with no usable X11 display | Enable native headless mode or run the process under a live Xvfb display. |
DISPLAY is set, but startup still fails |
No X server is listening at that value, or the user lacks Xauthority access | Check the X server on the browser host and run Selenium with matching authorization. |
| Works interactively but fails in Jenkins | The service account has a different environment, PATH or home directory | Log variables and versions inside the job; configure headless/Xvfb in the job itself. |
| Works locally but fails in Docker | The image lacks a browser, driver or display service | Install the required binaries in the image and choose headless or start Xvfb as the container entrypoint. |
| Grid client connects, but the node reports display errors | Display configuration was applied to the hub or client, not the node | Fix the node’s browser options, Xvfb process and environment. |
| Tests hang after a failure | Browser or Xvfb processes remain alive | Use finally cleanup, terminate child processes and ensure the display server is stopped. |
Performance, reliability and cost considerations
Native headless mode generally has the fewest moving parts: there is no X server to start, reserve or authenticate. Xvfb adds a process and memory overhead but is the safer compatibility choice when headed behavior, screenshots or video capture are part of the test contract. Grid adds network latency and capacity planning in exchange for remote execution and parallelism.
Do not treat the Grid RAM guidance as a fixed price or capacity formula. Measure your own browser mix, page complexity and concurrency, then cap sessions so a worker does not thrash. Cache or preinstall browser and driver packages where your CI policy permits, and retain version logs so a failed run can be reproduced.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Or skip the browser setup
If your goal is a clean website image or PDF rather than an interactive Selenium test, ScreenshotNeo provides a single HTTP request without maintaining Chrome, Firefox, Xvfb or a Grid node. Before capture it accepts cookie or consent banners as a visitor and removes more than 60 known consent platforms, newsletter popups and chat widgets; each cleanup step can be disabled. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads and cache hits are not billed, and the response reports the result through X-Page-Verdict and X-Billed headers.
Use the ScreenshotNeo API documentation for the full option set. This one-call example captures Stripe as WebP:
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.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpPython
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)Node.js
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 also offers an MCP server with take_screenshot, get_page_info and capture_pdf tools for Claude, Cursor and other MCP clients. Its options include full-page capture with lazy images loaded, CSS-selector element capture, dark mode, device presets or custom viewports, retina scale, PDF paper settings and page ranges, custom CSS and JavaScript, clicks, selector waits, network-idle waits, request/resource blocking, cookies and headers, timezone and geolocation, transparent backgrounds, resizing, chosen cache TTLs, signed image links, asynchronous webhooks, bulk capture of up to 100 URLs per call, usage reporting and an OpenAPI specification. Existing parameter names used by other screenshot APIs also work for easier migration.
The Free plan includes 1,000 shots each month with no card. Paid plans start at $5 for 3,000 shots; every feature is available on every plan, and annual billing gives two months free. Create a free ScreenshotNeo account to try it.
Frequently Asked Questions
Does this error indicate a failed CSS selector or page assertion?
No. “No display specified” occurs while the browser is starting, before Selenium can navigate to a page or evaluate a locator. Fix the display strategy first, then investigate page-level test failures separately.
Can I use native headless mode and Xvfb at the same time?
Usually choose one. Native headless does not need X11; Xvfb is for a headed browser that still needs a display. Running both adds complexity without solving a missing-display problem.
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.
