Firefox capabilities

geckodriver has a few capabilities that are specific to Firefox.


A dictionary used to define options which control how Firefox gets started and run. It may contain any of the following fields:

Name Type Description
binary string

Absolute path of the Firefox binary to select which custom browser binary to use. If left undefined geckodriver will attempt to deduce the default location of Firefox on the current system.

On macOS the path must be absolute to the browser binary, e.g. /Applications/ Specifying an application bundle such as /Applications/ will not work.

args array of strings

Command line arguments to pass to the Firefox binary. These must include the leading dash (-) where required, e.g. ["-devtools"].

To have geckodriver pick up an existing profile on the filesystem, you may pass ["-profile", "/path/to/profile"].

profile string

Base64-encoded ZIP of a profile directory to use for the Firefox instance. This may be used to e.g. install extensions or custom certificates, but for setting custom preferences we recommend using the prefs entry instead of passing a profile.

Profiles are created in the system’s temporary folder. This is also where the encoded profile is extracted when profile is provided. By default, geckodriver will create a new profile in this location.

The effective profile in use by the WebDriver session is returned to the user in the moz:profile capability in the new session response.

To have geckodriver pick up an existing profile on the filesystem, please set the args field to {"args": ["-profile", "/path/to/your/profile"]}.

log log object To increase the logging verbosity of geckodriver and Firefox, you may pass a log object that may look like {"log": {"level": "trace"}} to include all trace-level logs and above.
prefs prefs object Map of preference name to preference value, which can be a string, a boolean or an integer.


A boolean value to indicate how the pointer origin for an action command will be calculated.

With Firefox 59 the calculation will be based on the requirements by the [WebDriver] specification. This means that the pointer origin is no longer computed based on the top and left position of the referenced element, but on the in-view center point.

To temporarily disable the WebDriver conformant behavior use false as value for this capability.

Please note that this capability exists only temporarily, and that it will be removed once all Selenium bindings can handle the new behavior.


A boolean value to indicate which kind of interactability checks to run when performing a click or sending keys to an elements. For Firefoxen prior to version 58.0 some legacy code as imported from an older version of FirefoxDriver was in use.

With Firefox 58 the interactability checks as required by the [WebDriver] specification are enabled by default. This means geckodriver will additionally check if an element is obscured by another when clicking, and if an element is focusable for sending keys.

Because of this change in behaviour, we are aware that some extra errors could be returned. In most cases the test in question might have to be updated so it’s conform with the new checks. But if the problem is located in geckodriver, then please raise an issue in the [issue tracker].

To temporarily disable the WebDriver conformant checks use false as value for this capability.

Please note that this capability exists only temporarily, and that it will be removed once the interactability checks have been stabilized.

log object

Name Type Description
level string Set the level of verbosity of geckodriver and Firefox. Available levels are trace, debug, config, info, warn, error, and fatal. If left undefined the default is info. The value is treated case-insensitively.

prefs object

Name Type Description
preference name string, number, boolean One entry per preference to override.

Capabilities example

The following example selects a specific Firefox binary to run with a prepared profile from the filesystem in headless mode (available on certain systems and recent Firefoxen). It also increases the number of IPC processes through a preference and enables more verbose logging.

    "capabilities": {
        "alwaysMatch": {
            "moz:firefoxOptions": {
                "binary": "/usr/local/firefox/bin/firefox",
                "args": ["-headless", "-profile", "/path/to/my/profile"],
                "prefs": {
                    "dom.ipc.processCount": 8
                "log": {
                    "level": "trace"