Available in over 90 languages, and compatible with Windows, Mac and Linux machines, Firefox works no matter what you’re using or where you are. Make sure your operating system is up to date for the best experience. Review system requirements. Put Firefox on all your devices. Headless mode is a very useful way to run Firefox. Just as it might sound, Firefox is run as normal, minus any visible UI components visible. Though not so useful for surfing the web, it comes into its own with automated testing. This article provides all you need to know about running headless Firefox.
Headless mode is a very useful way to run Firefox. Just as it might sound, Firefox is run as normal, minus any visible UI components visible. Though not so useful for surfing the web, it comes into its own with automated testing. This article provides all you need to know about running headless Firefox.
Using headless mode
This section provides usage instructions for headless mode.
Basic usage
You can run Firefox in headless mode from the command line, by including the -headless flag. For example:
You need to run your headless Firefox with a new profile, otherwise you'll run into an error because you can't have two instances open with the same profile.
To create a new profile, go to the about:profiles page in Firefox and use the Create a New Profile button.
Once created, you can specify running firefox with the new profile usig the -P flag followed by the name of the profile:
Taking screenshots
Since Firefox 57, the --screenshot flag allows you to take screenshots of websites. The basic usage is as follows:
This creates a full-height screenshot of https://developer.mozilla.com/en-US/ called screenshot.png, in the active directory, with a viewport width of 800px.
You can omit -headless when using --screenshot, as it is implied:
To override the default values, mentioned above, you can use the following flags/features:
--screenshot name url— Set a custom name for the screenshot by including it between the--screenshotflag and the URL you want to capture. You can specify other web-compatible image formats such as.jpg,.bmp, etc.--window-size=x— Set a custom viewport width when taking the screenshot (full height is maintained). Note that the single argument version of this doesn't work.--window-size=x,y— Set a custom viewport width and height to capture.
For example, the following command creates a screenshot of https://developer.mozilla.com, in the active directory called test.jpg, with a viewport width of 800px, and a height of 1000px:
Note: There is a bug whereby taking a screenshot can sometimes fail if the specified URL is redirected (see Headless doesn't work when redirect is involved). Make sure you specify the final URL that you want to screenshot.
Automated testing with headless mode
The most useful way to use headless Firefox, is to run automated tests. You can make your testing process much more efficient.
Selenium in Node.js
Here we'll create a Selenium test, using Node.js and the selenium-webdriver package. For this guide, we'll assume that you already have basic familiarity with Selenium, Webdriver, and Node, and you already have a testing environment created. If not, work through our Setting up Selenium in Node guide, and return when you have.
First, confirm you've installed Node and the selenium-webdriver on your system. Then create a new file, called selenium-test.js, and follow the steps below to populate it with test code.
Note: Alternatively, you could clone our headless-examples repo. This also includes a package file, so you can just use npm install to install necessary dependencies.
Let's add some code. Inside this file, start by importing the main
selenium-webdrivermodule, and thefirefoxsubmodule:Next, we create a new
optionsobject, and add the-headlessargument to tell the driver instance we create below to run in headless mode:
Now let's create a new driver instance for Firefox, using setFirefoxOptions() to include our options object:
Alternatively, you can use options to set the binary and the headless arguments:
Finally, add the following code, which performs a simple test on the Google search homepage:
Finally, run your test with following command:
That's it! After a few seconds, you should see the message 'Test passed' returned in the console.
Headless Firefox in Node.js with selenium-webdriver, by Myk Melez, contains additional useful tips and tricks for running Node.js Selenium tests with headless mode.
Selenium in Java
Note: Thanks a lot to nicholasdipiazza for writing these instructions!
This guide assumes you already have Geckodriver on your machine, as explained in Setting up Selenium in Node, and an IDE set up which supports Gradle projects.
Download our headlessfirefox-gradle.zip archive (see the source here). Extract it, and import the headlessfirefox folder into your IDE, as a gradle project.
Edit the
build.gradlefile, to set selenium to a later version, if needed. At the time of writing, we used 3.5.3.Edit the
webdriver.gecko.driverproperty, in the HeadlessFirefoxSeleniumExample.java file, to equal the path where you installed geckodriver (see line 15 below).Run the java class, and you should see the HTML content of this page printed in your console/terminal.
Selenium in Python
This guide assumes you already have geckodriver on your machine, as explained in Setting up Selenium in Node.
Install the latest version of the Python client for Selenium.
Edit the following, to set the
executable_pathon line 11, to the path where you installed geckodriver:Run the Python script, and you should see the HTML content of this page printed in your console/terminal.
Debugging headless Firefox
You need to set a few preferences to allow remote debugging:
The example above shows the capabilities block required for WebdriverIO, other tools would require the same configuration. Then you will need to follow the remote debugging instructions.
Troubleshooting and further help
If you are having trouble getting headless mode to work, then do not worry — we are here to help. This section is designed to be added to as more questions arise, and answers are found.
- On Linux, certain libraries are currently required on your system, even though headless mode doesn't use them, as Firefox links against them. See bug 1372998, for more details and progress towards a fix.
If you want to ask the engineers a question, the best place to go is the #headless channel on Mozilla IRC. If you are pretty sure you've found a bug, file it on Mozilla Bugzilla.
See also
- Using Selenium with Headless Firefox (on Windows) by Andre Perunicic (uses Python)
- Headless Firefox in Node.js with selenium-webdriver by Myk Melez
- Using Selenium with Headless Firefox on Travis-CI by Josef Rousek
- TestCafe (v.0.18.0 and higher) also supports testing in headless Firefox, by default. See the documentation for the details.
- 1Downloaded blacklist
- 2Compiled-in blacklist
- 2.1On Windows
To request a block, file a bug using the appropriate request form and filling in all requested details:
On desktop
This is a list of all the GPU/driver/OS combinations that we have blocked using the downloaded Video card blacklisting feature of Firefox 4.
| GPU | Driver | OS | Features | Reason | Bug |
|---|---|---|---|---|---|
| NVIDIA NVS 3100M | <= 258.96 | Windows 7 | Layers acceleration and Direct2D | Driver crashes multiple times per day | bug 635044 |
| All NVIDIA hardware | >= 7.0.0.0 | Windows XP | Layers acceleration | Driver version does not match known NVIDIA drivers | bug 638936, bug 639698 |
| All AMD/ATI hardware | 8.982.0.0 | Windows | Layers acceleration and Direct2D | Firefox crashes multiple times per day | bug 792480, bug 793869 |
| All NVIDIA&Intel hardware | All | >= Mac OS X 10.6 | WebGL anti-aliasing | Security issues | bug 809550 |
| AMD Radeon HD 6290/6300/6310/6320 | All | Windows 7 | Layers acceleration and Direct2D | Firefox crashes multiple times per day | bug 840161 |
On Android
This is a list of all the Hardware/OS combinations that we have blocked using the downloaded StageFright decoding blacklisting feature introduced in Firefox 17 for Android.
| Hardware | OS | Feature | Reason | Bug |
|---|---|---|---|---|
| None |
The compiled-in blacklist is implemented separately for each OS/platform (Windows, Mac, X11). This list is presented for historical reasons, and is not currently up to date.
On Windows
All vendors other than AMD/ATI, NVIDIA, Intel are blocked (bug 623338). This was required primarily by various crashes on virtual machines with unusual vendor names (bug 621411). We're open to whitelisting more vendors if needed.
Windows 2003 is identified as Windows XP for the present purposes.
Layers acceleration is blocked on Windows versions older than Windows XP.
NVIDIA cards
We require NVIDIA driver version 257.21 (June 2010) or newer, see bug 623338. Notice that 257.21 is the commercial version number. This corresponds to the last 5 digits in the technical version number, which for instance is 8.17.12.5721 on Windows 7/Vista.
On NVIDIA GeForce 6100/6150/6200 TurboCache cards, we block Direct3D 9 accelerated layers, see bug 612007, bug 644787, bug 645872.
On Optimus devices, ANGLE rendering for WebGL is blocked (bug 636870). So WebGL should still work, but will use the OpenGL driver.
AMD/ATI cards
We require AMD driver version 10.6 (June 2010) or newer on Windows up to 7, see bug 623338. Notice that 10.6 is the commercial version number. The actual check is performed on the technical version number, and we require it to be at least 8.741.0.0.
Install Firefox Driver For Selenium Mac
We require AMD driver version greater than 12.11 beta (November 2012) on Windows 8, see bug 806991. Notice that 12.11 beta is the commercial version number. The actual check is performed on the technical version number, and we require it to be strictly higher than 9.10.8.0.
We block the OpenGL drivers on AMD cards on Windows, see bug 619773. This does not affect default functionality, as we use ANGLE instead of OpenGL by default for WebGL rendering anyway.
Intel cards
We require the following Intel driver versions, or newer (September 2010), see bug 594877.
- You can determine the driver version by entering about:support in the Firefox location bar; look under the Graphics section.
- The 'GPU family' below doesn't necessarily match the 'Adapter Description' in about:support. Indeed, Intel has multiple, overlapping product numbering schemes. For example, the '965 chipset family' encompasses the Q965 which is a GMA 3150 chip, and the G965 which is a GMA X3000 chip. Details of your Intel graphics chip are available from the Adapter tab of the Display Settings dialog in Windows. For example, in Windows Vista, one way to get to this in Windows Vista is right-click the desktop, choose Personalize > Display Settings > Display Settings > Monitor > Advanced Settings... > Adapter, and look for the Adapter String under Adapter Information.
- Intel GPUs have been grouped by families in the table below. For example, by 'GMA X3000' we mean all Intel GMA X3000, X3100, X3500 products.
| Windows version | GPU family | Required driver version |
|---|---|---|
| Windows XP | Intel GMA 500 | 6.14.11.1018 |
| Windows XP | Intel GMA 900 | 6.14.10.4764 |
| Windows XP | Intel GMA 950 | 6.14.10.4926 |
| Windows XP | Intel GMA 3150 | 6.14.10.5260 |
| Windows XP | Intel GMA X3000 | 6.14.10.5218 |
| Windows XP | Intel GMA X4500/HD | 6.14.10.5284 |
| Windows Vista | Intel GMA 500 | 7.14.10.1006 |
| Windows Vista | Intel GMA 900 | All versions are blocked |
| Windows Vista | Intel GMA 950 | 7.14.10.1504 |
| Windows Vista | Intel GMA 3150 | 7.14.10.2124 |
| Windows Vista | Intel GMA X3000 | 7.15.10.1666 |
| Windows Vista | Intel GMA X4500/HD | 8.15.10.2202 |
| Windows 7 | Intel GMA 500 | 5.0.0.2026 |
| Windows 7 | Intel GMA 900 | All versions are blocked |
| Windows 7 | Intel GMA 950 | 8.15.10.1930 |
| Windows 7 | Intel GMA 3150 | 8.14.10.2117 |
| Windows 7 | Intel GMA X3000 | 8.15.10.1930 |
| Windows 7 | Intel HD Graphics Ironlake | 8.15.10.2202 up to Firefox 19 > 8.15.10.2302 in Firefox 20 and above (see bug 843273) |
| Windows 7 | Intel GMA X4500 and other HD Graphics | 8.15.10.2202 |
| Windows 8 | Intel HD Graphics Ironlake | > 8.15.10.2302 in Firefox 23 and above (see bug 804144) |
We block Direct3D 10 features (including Direct2D) on buggy installations where the Intel driver version reported in the Windows Registry is not equal to the version of the driver DLL, igd10umd32.dll/igd10umd64.dll. See bug 590373.
Up to and including Firefox 6, on certain GPUs in the GMA X3000 generation (G35, GL960, GM965), we block Direct2D. See bug 595364. In Firefox 7 and newer, Direct2D is no longer blacklisted on these GPUs.
We block the OpenGL drivers on Intel cards on Windows, see bug 625118. This does not affect default functionality, as we use ANGLE instead of OpenGL by default for WebGL rendering anyway.
Dual-GPU systems
Our current blacklisting implementation does not properly support dual-GPU systems (bug 628129).
On Mac
For WebGL, we require Mac OS version 10.6 or newer. See bug 636611
For layers acceleration, we require Mac OS version 10.6.3 or newer. See bug 629016. One exception is <video> acceleration, which is enabled on all Mac OS versions.
For layers acceleration, we also block all old graphics adapters that do not fully support OpenGL 2.1 in hardware (use slow software fallbacks), or that can't render to non-power-of-two texture-backed framebuffers. That includes the following generations of GPUs: ATI Radeon X1000 and older, NVIDIA Geforce FX and older, and Intel GMA 950 and older.
For MSAA, we block all ATI cards except for AMD Radeon HD 6490M (device id 0x6760) and ATI Radeon HD 4670 (device id 0x9488). See Chromium issue 83153 [1].
On X11
XRender is used via Cairo, and is not subject to any blacklisting.
WebGL is enabled by default, so it works if your OpenGL driver is whitelisted or if you bypass the blocking (see below).
GL layers acceleration is not yet enabled by default (see bug 594876). You can enable it by setting layers.acceleration.force-enabled=true in about:config.
The following drivers are whitelisted:
- Mesa drivers are whitelisted if the Mesa version is at least 7.10.3 (see bug 659560).
- Exception: with the Nouveau 3D driver, the Mesa version is required to be at least 8.0 (see bug 729817)
- For the NVIDIA driver, versions 257.21 and newer are whitelisted, exactly like on Windows (see above).
- For the FGLRX (proprietary ATI) driver, we whitelist the newer versions that implement OpenGL 3.0 or newer. Indeed, FGLRX does not return any version number of its own, so we had to use the OpenGL version as a differentiator.
- FGLRX is blacklisted when the Linux kernel version is 2.6.32.
On Android
WebGL is disabled for Adreno 200/205 GPUs (see bug 736123).
StageFright software decoding (see bug 759945) and/or hardware decoding (see bug 782508) are enabled depending on the Android version, Firefox version and device capability:
| Android version | Device | First version | Bug |
|---|---|---|---|
| 2.2 | LG devices | Firefox 21 | bug 823253 |
| 2.3 | HTC and Samsung devices | Firefox 21 | bug 823253 |
| 3.x | Samsung devices | Firefox 21 | bug 823253 |
| 4.0 | Samsung devices and Galaxy Nexus | Firefox 17 | bug 806369 |
| 4.0 | Sony Xperia Ion (LT28h) | Firefox 22 | bug 845639 |
| 4.1, 4.2, 4.3 | Any devices | Firefox 17 | bug 806369 |
The following devices or hardware are blocked for StageFright decoding even if they are in the table above:
| Android version | Device | Hardware | First version | Reason | Bug |
|---|---|---|---|---|---|
| All | - | antares, endeavoru, harmony, picasso, picasso_e, ventana, rk30board | Firefox 21 | Crashes | bug 862523, bug 863843 |
| 2.3 | Samsung GT-I8160, GT-I8160L, GT-I8530, GT-I9070, GT-I9070P, GT-I8160P, GT-S7500, GT-S7500T, GT-S7500L, GT-S6500T | - | Firefox 21 | Crashes | bug 847837 |
| 2.3 | - | smdkc110, smdkc210, herring, shw-m110s, shw-m180s, n1, latona, aalto, atlas, qcom | Firefox 21 | Crashes | bug 864734 |
| 2.3 | Samsung SGH-T989 | - | Firefox 23 | Crashes | bug 818363 |
| 4.0 | Samsung SGH-I717, SGH-I727, SGH-I757, SGH-T989 | - | Firefox 21 | Crashes | bug 845729 |
| 4.1 | Samsung GT-P3100, GT-P3110, GT-P3113, GT-P5100, GT-P5110, GT-P5113 | - | Firefox 22 | Crashes | bug 853522 |
| 4.1 | Motorola XT890 | - | Firefox 24 | Crashes | bug 882342 |
| 4.1 | Sony devices | - | Firefox 21 | Crashes | bug 845734 |
| 4.1 | Sony Ericsson devices | - | Firefox 22 | Crashes | bug 879172 |
| 4.2 | Sony Ericsson devices | - | Firefox 23 | Crashes | bug 889433 |
If you would like to forcibly enable a graphics feature that is blocked on your system, follow these instructions. Warning: do this at your own risk. There usually are good reasons why features are blocked.
To force-enable WebGL, go to about:config and set webgl.force-enabled=true.
To force-enable WebGL anti-aliasing, go to about:config and set webgl.msaa-force=true.
Latest Firefox For Mac
To force-enable Layers Acceleration, go to about:config and set layers.acceleration.force-enabled=true.
On Windows Vista and Windows 7, to force-enable Direct2D Content Acceleration, go to about:config and set gfx.direct2d.force-enabled=true.
Firefox Driver Macos
On Android, to force-enable StageFright software decoding, go to about:config and set stagefright.force-enabled=true.
On Windows, you can also spoof your graphics system information to help debug driver blacklisting issues (see bug 604771):
- Create spoofed-firefox.bat in the installation folder (e.g. C:Program Files (x86)Mozilla Firefox)
- Set the new values of spoofed variables ending with a command to launch Firefox:
SET MOZ_GFX_SPOOF_WINDOWS_VERSION=60001
SET MOZ_GFX_SPOOF_VENDOR_ID=0x8086
SET MOZ_GFX_SPOOF_DEVICE_ID=0x0046
SET MOZ_GFX_SPOOF_DRIVER_VERSION=8.15.10.2302
'C:Program Files (x86)Mozilla Firefoxfirefox.exe' -p -no-remote - Double-click spoofed-firefox.bat and create a profile if required
- Click the Firefox button, then select Help, finally Troubleshooting Information and check the Graphics section.
If force-enabling a feature doesn't work, that probably means that your hardware doesn't support it. For example, layers acceleration currently requires support for 4Kx4K textures, which rules out some graphics cards, like the Intel G31/G33.