Overview
GeckoDriverService manages the lifecycle of the geckodriver process that bridges Selenium WebDriver commands to the Firefox browser via the Marionette protocol.
Description
The GeckoDriverService class extends FirefoxDriverService (which itself extends DriverService) and is responsible for starting, configuring, and stopping the geckodriver executable. It exposes system properties and environment variables for locating the geckodriver binary (webdriver.gecko.driver / SE_GECKODRIVER), configuring log output (webdriver.firefox.logfile, webdriver.firefox.logLevel), controlling log truncation (webdriver.firefox.logTruncate), and setting a custom profile root directory (webdriver.firefox.profileRoot). The inner Builder class (annotated with @AutoService for automatic discovery) constructs geckodriver command-line arguments including port assignment, WebSocket port for BiDi communication, Marionette port for connecting to existing Firefox instances, log level, log truncation, profile root, and allowed hosts. The service waits for geckodriver availability by probing the assigned port and does not use a shutdown endpoint.
Usage
Use GeckoDriverService when you need fine-grained control over how geckodriver is launched, such as specifying a custom log level, profile root directory, WebSocket port, or connecting to an existing Firefox instance. For most use cases, GeckoDriverService.createDefaultService() or the automatic service discovery via FirefoxDriver is sufficient.
Code Reference
Source Location
Signature
public class GeckoDriverService extends FirefoxDriverService {
public static final String GECKO_DRIVER_NAME = "geckodriver";
public static final String GECKO_DRIVER_EXE_PROPERTY = "webdriver.gecko.driver";
public static final String GECKO_DRIVER_EXE_ENVIRONMENT_VARIABLE = "SE_GECKODRIVER";
public static final String GECKO_DRIVER_LOG_PROPERTY = "webdriver.firefox.logfile";
public static final String GECKO_DRIVER_LOG_LEVEL_PROPERTY = "webdriver.firefox.logLevel";
public static final String GECKO_DRIVER_LOG_NO_TRUNCATE = "webdriver.firefox.logTruncate";
public static final String GECKO_DRIVER_PROFILE_ROOT = "webdriver.firefox.profileRoot";
public GeckoDriverService(File executable, int port, Duration timeout,
List<String> args, Map<String, String> environment) throws IOException
public static GeckoDriverService createDefaultService()
public String getDriverName()
public String getDriverProperty()
public String getDriverEnvironmentVariable()
public Capabilities getDefaultDriverOptions()
// Inner Builder class
public static class Builder extends FirefoxDriverService.Builder<GeckoDriverService, Builder> {
public Builder withAllowHosts(String allowHosts)
public Builder withLogLevel(FirefoxDriverLogLevel logLevel)
public Builder withTruncatedLogs(Boolean truncate)
public Builder withProfileRoot(File root)
public Builder connectToExisting(int marionettePort)
public Builder withWebSocketPort(Integer websocketPort)
public int score(Capabilities capabilities)
}
}
Import
import org.openqa.selenium.firefox.GeckoDriverService;
I/O Contract
Constructor Parameters
| Parameter |
Type |
Description
|
executable |
File (nullable) |
Path to the geckodriver executable.
|
port |
int |
Port number on which geckodriver will listen.
|
timeout |
Duration (nullable) |
Maximum time to wait for geckodriver to start.
|
args |
List<String> (nullable) |
Command-line arguments passed to geckodriver.
|
environment |
Map<String, String> (nullable) |
Environment variables for the geckodriver process.
|
Builder Methods
| Method |
Input |
Description
|
withAllowHosts |
String |
Space-separated list of allowed Host header values for incoming requests.
|
withLogLevel |
FirefoxDriverLogLevel |
Sets the geckodriver log verbosity level.
|
withTruncatedLogs |
Boolean |
Controls whether long log lines are truncated (default: true). Set to false to disable.
|
withProfileRoot |
File |
Directory for storing temporary profiles (useful when default temp dir lacks write permissions).
|
connectToExisting |
int |
Connects to an existing Firefox instance via the given Marionette port instead of launching a new one.
|
withWebSocketPort |
Integer |
Sets the WebSocket port for BiDi communication; 0 auto-allocates a free port.
|
build |
none |
Constructs and returns a configured GeckoDriverService instance.
|
System Properties
| Property |
Description
|
webdriver.gecko.driver |
Path to the geckodriver executable.
|
webdriver.firefox.logfile |
Path to the geckodriver log output file.
|
webdriver.firefox.logLevel |
Log level string (e.g., "debug", "info").
|
webdriver.firefox.logTruncate |
Set to true to disable log line truncation.
|
webdriver.firefox.profileRoot |
Root directory for temporary profile storage.
|
Exceptions
| Exception |
Condition
|
IOException |
Thrown during construction if I/O errors occur.
|
WebDriverException |
Wraps IOException in createDriverService.
|
Usage Examples
// Create a default GeckoDriverService
GeckoDriverService service = GeckoDriverService.createDefaultService();
WebDriver driver = new FirefoxDriver(service);
// Create a customized GeckoDriverService using the Builder
GeckoDriverService service = new GeckoDriverService.Builder()
.withLogLevel(FirefoxDriverLogLevel.DEBUG)
.withTruncatedLogs(false)
.withProfileRoot(new File("/tmp/firefox-profiles"))
.build();
WebDriver driver = new FirefoxDriver(service);
// Connect to an existing Firefox instance via Marionette
GeckoDriverService service = new GeckoDriverService.Builder()
.connectToExisting(2828)
.build();
WebDriver driver = new FirefoxDriver(service);
// Configure with allowed hosts and a specific WebSocket port
GeckoDriverService service = new GeckoDriverService.Builder()
.withAllowHosts("localhost 127.0.0.1")
.withWebSocketPort(9222)
.build();
WebDriver driver = new FirefoxDriver(service);
Related Pages
- FirefoxDriver - Primary consumer that uses GeckoDriverService to manage geckodriver
- FirefoxOptions - Provides default driver options returned by
getDefaultDriverOptions()
- FirefoxDriverLogLevel - Enum used by
withLogLevel() to configure log verbosity
- FirefoxProfile - Profile object whose root directory can be configured via
withProfileRoot()
- HasContext - Context-switching capability available on FirefoxDriver sessions started via this service
