Gecko (Marionette) Driver Selenium: Download, Install, Use with Firefox

What is Gecko Driver?

The term Gecko stands for a Web Browser engine that is inbuilt within Mozilla Firefox browser. Gecko driver acts as a proxy between Web Driver enabled clients(Eclipse, Netbeans, etc.) and Mozilla Firefox browser. In short, Gecko driver acts as a link between Selenium Web Driver tests and Mozilla Firefox browser.

Before Selenium 3, Mozilla Firefox browser was the default browser for Selenium. After Selenium 3, testers need to initialize the script to use Firefox using GeckoDriver explicitly. Selenium uses W3C Webdriver protocol to send requests to GeckoDriver, which translates them into a protocol named Marionette. Firefox will understand the commands transmitted in the form of Marionette protocol and executes them.

Advantage of using Gecko Driver

Selenium Webdriver version 2.53 is not compatible with Mozilla Firefox version 47.0+. The Firefox driver used in earlier versions of Mozilla Firefox will be discontinued, and only the GeckoDriver implementation would be used. Hence testers are forced to use GeckoDriver if they want to run automated tests on Mozilla Firefox version 47.0+. But the big question – what is the advantage?

The major advantage of using GeckoDriver as opposed to the default Firefox driver is Compatibility. GeckoDriver uses W3C WebDriver protocol to communicate with Selenium. W3C is a universally defined standard for Web Driver. This means Selenium Developers (People who code Selenium base) need not create a new version of Web Driver for each browser version. The same Web Driver can be used for multiple browser versions. Hence, GeckoDriver is preferred compared to the earlier implementation of Firefox driver.

Download and Install Gecko Driver:

Gecko Driver is available as an executable file that can be downloaded on the system. The following are the list of steps to download gecko driver.

Step 1 ) At this page ,Select the appropriate version for GeckoDriver download based on your operating system

Step 2) Once the ZIP file download is complete, extract the contents of ZIP File onto a file folder

Step 3) Note the location where you extracted the driver. Location will be used later to instantiate the driver.

Ways to initialize GeckoDriver:

There are three different ways to initialize GeckoDriver.

1. Using DesiredCapabilities:

First, set the system property for Gecko Driver.


System.setProperty("webdriver.gecko.driver","Path to geckdriver.exe file");



Next, set Desired Capabilities.

Desired Capabilities help Selenium to understand the browser name, version and operating system to execute the automated tests. Below is the code to set gecko driver using DesiredCapabilities class.

DesiredCapabilities capabilities = DesiredCapabilities.firefox();

Here is the complete code

System.setProperty("webdriver.gecko.driver", driverPath);
DesiredCapabilities capabilities = DesiredCapabilities.firefox();
driver= new FirefoxDriver(capabilities);

2. Using marionette property:

Gecko driver can also be initialized using marionette property as below


If gecko driver is initialized using the above method, code for desired capabilities is not required.

3. Using FirefoxOptions:

Mozilla Firefox version 47+ has marionette driver as a legacy system. Taking advantage of this, marionette driver can be called using Firefox Options as below

FirefoxOptions options = new FirefoxOptions();

Code for launching firefox using Gecko driver :

package com.guru99.demo;

import org.junit.After;
import org.junit.Before;
import org.junit.Test;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.firefox.FirefoxDriver;
import org.openqa.selenium.remote.DesiredCapabilities;

public class GeckoDriverDemo {

    String driverPath = "D:\\Guru99Demo\\GeckoDriver.exe";
    public WebDriver driver;

    public void startBrowser() {
        System.setProperty("webdriver.gecko.driver", driverPath);
        DesiredCapabilities capabilities = DesiredCapabilities.firefox();
        capabilities.setCapability("marionette", true);
        driver = new FirefoxDriver(capabilities);


    public void navigateToUrl() {

    public void endTest() {


Code Explanation:

@Before method:

Initially, we need to set the system property for gecko driver to the geckdriver.exe file download location. We need to set the marionette property to true for Selenium to use Marionette protocol to communicate with Gecko Driver. Finally, we need to start the Firefox browser instance using the object for Desired Capabilities.

The below statements help to achieve the above task.

System.setProperty("webdriver.gecko.driver", driverPath);
DesiredCapabilities capabilities = DesiredCapabilities.firefox();
driver= new FirefoxDriver(capabilities);

@Test method:

We are navigating to user-specified URL using the inbuilt “get” method provided by Selenium web driver. The below statement help to achieve the same.


@After method:

Finally, we are closing the browser instance using the quit method.


Modify a script for non- Gecko to Gecko:

Non-gecko driver script used before Selenium 3 was straightforward. We need to create an instance of Firefox driver and use the instance variable.

public void startBrowser() {
    driver = new FirefoxDriver();


To convert to gecko, you need to simply add one line of code

    public void startBrowser() {
        System.setProperty("webdriver.gecko.driver", "D:\\Downloads\\GeckoDriver.exe");
        driver = new FirefoxDriver();


Common exceptions occurred while using Gecko Driver:

Following is a list of common exceptions that occur while using Gecko Driver and with resolution.

1. The path to driver executable must be set by webdriver.gecko.driver system property:

This exception occurs when user tries to instantiate Firefox driver without setting the system property for gecko driver. This is usually done by beginners to Selenium who are not aware of the changes made from Selenium 3 to Selenium previous versions.

The resolution for the above exception is to set the system property for gecko driver with the location of geckodriver.exe file as below

System.setProperty("webdriver.gecko.driver", "D:\\Downloads\\geckodriver.exe");

Please note that you need to set the property of gecko driver before creating an instance of Mozilla Firefox driver.

2. Firefox Not Connected Exception:

org.openqa.selenium.firefox.NotConnectedException: Unable to connect to host on port 7055 after 45000 ms.

This exception usually occurs when Firefox version has been upgraded to the latest version. The resolution for this exception is to update the selenium jar file and gecko driver to the latest version and use the same.

3. Session Not Created Exception:

org.openqa.selenium.SessionNotCreatedException: Unable to create new remote session.

This exception occurs due to compatibility issues between Selenium and Gecko driver. Gecko driver works with Firefox version 47 or above. It can be resolved by updating Firefox version to 47 or above.

4. Connection Refused Exception:

WebDriver Exception: Connection Refused

This exception is the message generated when web driver is unable to establish a connection with Firefox. It can be resolved using any one of the following techniques.

  • Use driver.quit() method to destroy earlier instances of web driver
  • Clean the browser cache before executing your automated tests
  • Clean the project workspace within Eclipse IDE
  • Always use the latest version of selenium gecko driver and most recent version of Firefox browser