a little madness

A man needs a little madness, or else he never dares cut the rope and be free -Nikos Kazantzakis


Running Selenium Headless

Our dog food Pulse server, which spends all day building itself, is a headless box. This presented no challenge for the Pulse 1.x series of releases, as our builds are all scripted and don’t require any GUI tools. With Pulse 2.0, however, things changed. As mentioned in my previous post, this new release has a whole new acceptance test suite based on Selenium. The problem is: Selenium runs in a real browser, and that browser requires a display.

Fortunately, the dog food server is also a Linux box. Thus there is no need to add in a full X setup with requisite hardware just to have Selenium running. This is thanks to the magic of Xvfb – the X virtual framebuffer. Basically, this is a stripped back X server that maintains a virtual display in memory. Hence no actual video hardware or driver is needed, and we can keep things simple.

Setting things up is straightforward. First, install Xvfb:

# apt-get install xvfb

on Debian/Ubuntu; or

# yum install xorg-x11-Xvfb

on Fedora/RedHat. Then, choose a display number that is unlikely to ever clash (even if you add a real display later) – something high like 99 should do. Run Xvfb on this display, with access control off1:

# Xvfb :99 -ac

Now you need to ensure that your display is set to 99 before running the Selenium server (which itself launches the browser). The easiest way to do this is to export DISPLAY=:99 into the environment for Selenium. First, make sure things are working from the command line like so:

$ export DISPLAY=:99
$ firefox

Firefox should launch without error, and stay running (until you kill it with Control-C or similar). You won’t see anything of course! If things go well, then you need to modify the way you launch the Selenium server to ensure the DISPLAY is set. There are many ways to do this, in our Pulse setup we actually use a resource as it is a convenient way to modify the build environment.

An alternative which may suit some setups is to use the xvfb-run wrapper to launch your Selenium server. I opted against this as Pulse has resources to modify the environment and this way I do not need to change the actual build scripts at all. However if you are not using Pulse (shame! :) ) then you may want to look into it.

1 If you are worried about access on your network, then using -ac long-term is not a good idea. Once you have things working, I would suggest tightening things up by turning access control on.

Liked this post? Share it!

37 Responses to “Running Selenium Headless”

  1. June 12th, 2008 at 6:30 am

    Alan says:

    Ugh … export DISPLAY=:99 …

    I’ve been messing around for an hour now trying to figure out how to pass a –display=xx option to Firefox from Selenium in order to get the damned thing running headless. Cheers for reminding me of the obvious!

  2. June 12th, 2008 at 11:20 am

    Jason says:

    Hi Alan,

    I’m glad someone found this post useful :). I was lucky as using the environment was natural in Pulse so I never considered an alternative.

  3. August 6th, 2008 at 1:21 pm

    Jim says:

    So, I was wondering if you’d be able to give me a hand with this.. I have Xvfb running (I think), and firefox-bin now runs on my headless gentoo box (when I run /usr/bin/firefox). However, when I try to run a Selenium script, the RC server errors with:

    java.lang.RuntimeException: File was a script file, not a real executable: /usr/bin/firefox-bin

    and the actual error from the attempted test run is:

    Any idea where I should get started? It’s definitely some sort of a setup issue – not a code bug (I have the same exact test running just fine on my not-so-headless ubuntu box). So, something with the environment vars? Or finding and moving the firefox binary somewhere else?

  4. August 6th, 2008 at 11:06 pm

    Jason says:

    Hi Jim,

    It looks like the file that Selenium is identifying as your firefox executable (/usr/bin/firefox-bin, or whatever that links to) is not a binary file, but a script. Selenium expects to find the binary file itself, and refuses to launch Firefox from a script. The solution is to find where the actual binary file is (you can probably tell from reading script and seeing what it launches), and point Selenium at it by setting the browser to:

    *firefox /path/to/the/real/binary

    when you create your Selenium instance.

  5. October 1st, 2008 at 8:20 am

    Pam says:

    Hi, thanks for the post. I’m having problems on Fedora 8 getting firefox to run with Xvfb… I’ve done everything except the pam stuff, because Fedora’s configured differently… anyone else?

  6. October 1st, 2008 at 8:46 am

    Pam says:

    Okay, what we had to do to get it working was:
    yum update firefox
    yum update xorg-x11-server-Xvfb
    yum update cairo

    Now firefox will work with the Xvfb on Fedora 8.

    We edited /etc/rc.d/rc.local to include:
    Xvfb :99 -ac -noreset &

    In Hudson (our CI server) we added a “shell execute” that did this:
    export LD_LIBRARY_PATH=”/usr/lib/firefox/”; export PATH=”$PATH:/usr/lib/firefox/”; export DISPLAY=:99;
    java -jar /usr/share/selenium-rc/selenium-server/selenium-server.jar -htmlSuite “*firefox /usr/lib/firefox/firefox-bin” “http://test-server/” “/var/www/html/hs/tests/TestSuite.html” “/var/www/html/hs/tests/selenium-results.html”

    Thanks for the good website.

    Also for anyone else trying to do this on Fedora 8, you don’t have to do the PAM stuff, and probably shouldn’t because it’s different.

  7. November 7th, 2008 at 5:31 pm

    Ankit says:

    It was really helpful post. Keep it up. But one thing I like to tell that DISPLAY=:99 does not work for tty terminal. As I want use so coz I want test this on server which has no X server running. Then What to do???
    I found one solution net which we can get screenshot using TTY terminal. I modified the script according to my need. Hope, you guys may find it helpful.


    If have any more Query, then feel free to contact. Catch me on,


  8. April 16th, 2009 at 9:27 pm

    songkai says:

    How come I always get the below error:

    Could not init font path element /usr/share/fonts/X11/cyrillic, removing from list!
    Could not init font path element /usr/share/fonts/X11/Type1, removing from list!
    Could not init font path element /var/lib/defoma/x-ttcidfont-conf.d/dirs/TrueType, removing from list!

    I already install xfonts-base xfonts-75dpi xfonts-100dpi

  9. June 22nd, 2009 at 7:03 pm

    Prashant Shah says:

    I am getting an exception from Fedora after installing Xvfb. It states (error opening security policy file /usr/lib/xserver/SecurityPolicy) on typing the command Xvfb :99 -ac. Any idea how I can fix this error?

  10. June 23rd, 2009 at 4:51 am

    Jason says:

    Hi Prashant,

    It may be that Xvfb is working despite this error. Did you try running something graphical after exporting your DISPLAY? If you try, say, an xterm, and it runs OK, then things are probably working. You can also take a screenshot of that display to check how things are looking. An easy way is with the import tool from ImageMagick:

    $ sudo yum install ImageMagick

    $ Xvfb :99 -ac &
    $ export DISPLAY=:99
    $ xterm &
    # Pause for a few moments
    $ import -window root screenshot.png

    Then open screenshot.png and see if your xterm is running.

  11. June 23rd, 2009 at 6:34 pm

    Prashant Shah says:

    Hi Jason,

    I tried the below mentioned commands and got the screenshot.png file which is not human readable. It has bunch of encoding stuff I believe. I also tried opening google homepage as:

    $DISPLAY=:99 firefox http://www.google.com

    The cursor never came back after I entered this command on the shell. Is firefox running and has it successfully launched google webpage? Then I said:

    $import -window root screenshot.png and fedora created the png file in the root folder. Although when I open it I don’t see Google webpage being launched…?

    Please help

  12. June 23rd, 2009 at 6:43 pm

    Jason says:

    Hi Prashant,

    The .png file is an image. You need to open it in an image viewer. Also, please don’t dump huge binary files in comments (I will delete the existing one).

  13. June 23rd, 2009 at 10:41 pm

    Prashant Shah says:

    I opened the .png in an image viewver and I don’t see the google webpage for which I made a request.

    I could sent you the png via email if required. I am not sure what is that I am doing wrong….

    $DISPLAY=:99 firefox http://www.google.com

    The cursor never came back after I entered this command on the shell. Is firefox running and has it successfully launched google webpage?

  14. August 20th, 2009 at 3:36 pm

    Matthew Hager says:

    If you are getting garbage screenshots try starting Xvfb like this: Xvfb :99 -screen 0 1024x768x24 -noreset &

  15. November 13th, 2009 at 4:38 am

    A Curious Use For Selenium – Slideshows | Kevin W. Gisi says:

    […] screenshots), set up the X virtual frame buffer out on my server (big thanks to this tutorial: Running Selenium Headless), and boom! Now, I’ve got PNG images of every slide in the deck, ready and available. Throw […]

  16. January 12th, 2010 at 9:04 am

    Martin Dale Lyness says:

    This was the first thing i looked at when I searched google for setting up my selenium tests on my fresh Ubuntu 9.10 server. I learned there is an issue with the default install for the new Ubuntu release.

    In case anyone else has issues with the Ubuntu 9.10 Xvfb package I’ve uploaded the 4 step fix I discovered, after a few hours of Googling, to my blog: http://blog.martin-lyness.com/archives/installing-xvfb-on-ubuntu-9-10-karmic-koala

  17. April 7th, 2010 at 11:18 pm

    Jigar shah says:

    Anything changes if i run selenium testcases with WebDriverBackedSelenium test ? Because this one stats browser of its own. So bit of trouble.

  18. June 15th, 2010 at 6:35 pm

    Jordan Sissel says:


    I wrote a small wrapper script that manages startup of the X server and window manager (similar to startx, but more direct).



    Mainly it lets you skip worrying about $DISPLAY as it automatically picks one for you which makes scaling to multiple firefox/xservers much easier.

  19. November 19th, 2010 at 2:26 am

    How can I run Selenium tests on an Ubuntu server? Drija says:

    […] i haven’t tested it by myself, but this sounds promising: http://www.alittlemadness.com/2008/03/05/running-selenium-headless/ […]

  20. January 24th, 2011 at 5:18 pm

    Selenium « ??.?? says:

    […] ?????1????2?Linux? xvfb-run java -jar selenium-server-standalone-2.0b1.jar ???xvfb? sudo apt-get install xvfb […]

  21. July 31st, 2011 at 9:19 am

    ThankfulReader says:

    Thanks very much. I found this useful.

  22. July 31st, 2011 at 11:19 pm

    Screen scraping using a headless selenium « Arg and gah and ap and pa says:

    […] then add code to create a headless selenium using Xvfb (see http://www.alittlemadness.com/2008/03/05/running-selenium-headless) which is then used for […]

  23. August 13th, 2011 at 2:27 am

    Init Selenium RC on headless server - Admins Goodies says:
  24. August 29th, 2011 at 12:25 am

    Jaya says:


    I could not use java code in selenium headless ,

    What should i do ?


  25. September 3rd, 2011 at 5:32 am

    Wilberto says:

    Thanks mate, you helped me a lot with this!

    Cheers and congrats.

  26. September 14th, 2011 at 6:08 am

    Running Selenium on headless Ubuntu 11.04 (like Ubuntu Server) with Xvfb | Hnygard.no says:

    […] Running Selenium Headless […]

  27. March 15th, 2012 at 4:35 pm

    john says:

    Thanks for this post. You really saved me a lot of time getting my test cases running in a headless environment.

    Cheers !

  28. May 23rd, 2012 at 8:49 pm

    Python – Firefox Headless | PHP Developer Resource says:

    […] http://www.alittlemadness.com/2008/03/05/running-selenium-headless/ Tagged: FirefoxheadlesspythonSelenium /* * * CONFIGURATION VARIABLES: EDIT BEFORE PASTING INTO YOUR WEBPAGE * * */ var disqus_shortname = 'dkphp'; // required: replace example with your forum shortname var disqus_identifier = "d590f679a1b1782cf749e7cc4eaece4b"; var disqus_url = "http://www.dkphp.com/questions-2/python/python-firefox-headless.html"; /* * * DON'T EDIT BELOW THIS LINE * * */ (function() { var dsq = document.createElement('script'); dsq.type = 'text/javascript'; dsq.async = true; dsq.src = 'http://' + disqus_shortname + '.disqus.com/embed.js'; (document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(dsq); })(); […]

  29. July 20th, 2012 at 2:48 am

    Allan Chappell says:


    I just created this to make life a little easier. You can stick this in a configuration management system such as Puppet or what not. Feel free to comment, contribute, and critique. I’m not the best shell programmer in the world so I’m sure this can use some help :P

  30. August 24th, 2012 at 7:23 pm

    Mahesh says:

    I am running the selenium code in the aws headless server abd facing the following exception:

    org.openqa.selenium.WebDriverException: org.openqa.selenium.WebDriverException: Failed to connect to binary FirefoxBinary(/opt/firefox/firefox-bin) on port 7055; process output follows:
    �*** e = [Exception… “Component returned failure code: 0x80570016 (NS_ERROR_XPC_GS_RETURNED_FAILURE) [nsIJSCID.getService]” nsresult: “0x80570016 (NS_ERROR_XPC_GS_RETURNED_FAILURE)” location: “JS frame :: chrome://browser/content/utilityOverlay.js :: getShellService :: line 339″ data: no]

    please can anyone help

  31. March 5th, 2013 at 9:28 pm

    Pratt G says:

    When I execute command as follows I get an error.

    C:\sele>java -jar selenium-server-standalone-2.25.0.jar -port 4546 -htmlSuite “*firefox” http://www.google.com/ “C:\sele\test_sel.html” “C:\sele\test.html”
    Mar 5, 2013 3:53:56 PM org.openqa.grid.selenium.GridLauncher main
    INFO: Launching a standalone server
    15:53:56.399 INFO – Java: Sun Microsystems Inc. 17.0-b17
    15:53:56.402 INFO – OS: Windows 7 6.1 x86
    15:53:56.408 INFO – v2.25.0, with Core v2.25.0. Built from revision 17482
    15:53:56.529 INFO – RemoteWebDriver instances should connect to:
    15:53:56.553 INFO – Version Jetty/5.1.x
    15:53:56.556 INFO – Started HttpContext[/selenium-server/driver,/selenium-server/driver]
    15:53:56.557 INFO – Started HttpContext[/selenium-server,/selenium-server]
    15:53:56.580 INFO – Started HttpContext[/,/]
    15:53:56.972 INFO – Started org.openqa.jetty.jetty.servlet.ServletHandler@a32b
    15:53:56.972 INFO – Started HttpContext[/wd,/wd]
    15:53:56.998 INFO – Started SocketListener on
    15:53:57.001 INFO – Started org.openqa.jetty.jetty.Server@1050e1f
    HTML suite exception seen:
    java.lang.RuntimeException: java.lang.RuntimeException: Firefox 3 could not be f
    ound in the path!
    Please add the directory containing ”firefox.exe” to your PATH environment
    variable, or explicitly specify a path to Firefox 3 like this:
    *firefox3 c:\blah\firefox.exe
    at org.openqa.selenium.server.browserlaunchers.BrowserLauncherFactory.createBrowserLauncher(BrowserLauncherFactory.java:175)
    at org.openqa.selenium.server.browserlaunchers.BrowserLauncherFactory.getBrowserLauncher(BrowserLauncherFactory.java:109)
    at org.openqa.selenium.server.htmlrunner.HTMLLauncher.getBrowserLauncher(HTMLLauncher.java:78)
    at org.openqa.selenium.server.htmlrunner.HTMLLauncher.runHTMLSuite(HTMLLauncher.java:138)
    at org.openqa.selenium.server.htmlrunner.HTMLLauncher.runHTMLSuite(HTMLLauncher.java:196)
    at org.openqa.selenium.server.SeleniumServer.runHtmlSuite(SeleniumServer.java:612)
    at org.openqa.selenium.server.SeleniumServer.boot(SeleniumServer.java:286)
    at org.openqa.selenium.server.SeleniumServer.main(SeleniumServer.java:244)
    at org.openqa.grid.selenium.GridLauncher.main(GridLauncher.java:54)
    Caused by: java.lang.RuntimeException: Firefox 3 could not be found in the path!

    Please add the directory containing ”firefox.exe” to your PATH environment
    variable, or explicitly specify a path to Firefox 3 like this:
    *firefox3 c:\blah\firefox.exe
    at org.openqa.selenium.browserlaunchers.locators.CombinedFirefoxLocator.findBrowserLocationOrFail(CombinedFirefoxLocator.java:49)
    at org.openqa.selenium.server.browserlaunchers.BrowserInstallationCache.locateBrowserInstallation(BrowserInstallationCache.java:46)
    at org.openqa.selenium.server.browserlaunchers.FirefoxLauncher.(FirefoxLauncher.java:58)
    at sun.reflect.NativeConstructorAccessorImpl.newInstance0(Native Method)
    at sun.reflect.NativeConstructorAccessorImpl.newInstance(Unknown Source)
    at sun.reflect.DelegatingConstructorAccessorImpl.newInstance(Unknown Source)
    at java.lang.reflect.Constructor.newInstance(Unknown Source)
    at org.openqa.selenium.server.browserlaunchers.BrowserLauncherFactory.createBrowserLauncher(BrowserLauncherFactory.java:164)
    … 8 more

    Please help me out with this error.

    Thanks in advance

  32. July 2nd, 2013 at 3:10 pm

    Setting up Selenium 2 and behat on Slackware Linux | Lysender's Daily Log Book says:

    […] run your Selenium driven tests on a headless VPS, try this tip from this site: a little madness blog. For Slackware box, follow the steps […]

  33. September 7th, 2013 at 3:25 am

    How can I run Selenium tests on an Ubuntu server? - Just just easy answers says:

    […] i haven’t tested it by myself, but this sounds promising: http://www.alittlemadness.com/2008/03/05/running-selenium-headless/ […]

  34. November 29th, 2013 at 3:43 am

    mvdb says:

    Have anyone had any issue with firefox crashing with iframes ? I’m processing a lot of iframes and at some point the driver freezes. Plus, this also happens without Xvfb (on a MacbookPro).

    Desperate here…

  35. June 20th, 2014 at 6:51 pm

    hide browser in Selenium RC | Coding and Programing says:

    […] You can run Selenium ‘headless’ on Linux. I’ve never tried doing this and doubt it’s really worth the effort. http://www.alittlemadness.com/2008/03/05/running-selenium-headless/ […]

  36. August 28th, 2014 at 9:40 pm

    Tao says:

    hi, I was wondering, why on Debian 7 desktop, there is always an warning when running Xvfb. The warning is the following:

    [dix] Could not init font path element /var/lib/defoma/x-ttcidfont-conf.d/dirs/TrueType, removing from list!

    I know it does not affect anything concerning my requirement, but it is quite annoying.

    Anyone have a solution.

    PS: I tried to install x-ttcidfont-conf, but debian replies that this package is obsolete.

  37. November 18th, 2014 at 10:02 pm

    hide browser in Selenium RC | Coding and Programing says:

    […] You can run Selenium ‘headless’ on Linux in XVFB. I’ve never tried doing this and doubt it’s really worth the effort. http://www.alittlemadness.com/2008/03/05/running-selenium-headless/ […]

Leave a Reply