Flags

--allow-hosts ALLOW_HOSTS…

Values of the Host header to allow for incoming requests.

By default the value of HOST is allowed. If --allow-hosts is provided, exactly the given values will be permitted. For example --allow-host geckodriver.test webdriver.local will allow requests with Host set to geckodriver.test or webdriver.local.

Requests with Host set to an IP address are always allowed.

--allow-origins ALLOW_ORIGINS…

Values of the Origin header to allow for incoming requests.

Origin is set by web browsers for all POST requests, and most other cross-origin requests. By default any request with an Origin header is rejected to protect against malicious websites trying to access geckodriver running on the local machine.

If --allow-origins is provided, web services running on the given origin will be able to make requests to geckodriver. For example --allow-origins https://webdriver.test:8080 will allow a web-based service on the origin with scheme https, hostname webdriver.test, and port 8080 to access the geckodriver instance.

--android-storage ANDROID_STORAGE

Deprecation warning: This argument is deprecated and planned to be removed with the 0.31.0 release of geckodriver. As such it shouldn’t be used with version 0.30.0 or later anymore. By default the automatic detection will now use the external storage location, which is always readable and writeable.

Selects the test data location on the Android device, eg. the Firefox profile. By default auto is used.

Value Description
auto Best suitable location based on whether the device is rooted.
If the device is rooted `internal` is used, otherwise `app`.
app

Location: `/data/data/%androidPackage%/test_root`

Based on the `androidPackage` capability that is passed as part of `moz:firefoxOptions` when creating a new session. Commands that change data in the app's directory are executed using run-as. This requires that the installed app is debuggable.
internal

Location: `/data/local/tmp/test_root`

The device must be rooted since when the app runs, files that are created in the profile, which is owned by the app user, cannot be changed by the shell user. Commands will be executed via `su`.
sdcard

Location: `$EXTERNAL_STORAGE/Android/data/%androidPackage%/files/test_root`

This location is supported by all versions of Android whether if the device is rooted or not.

-b BINARY / --binary BINARY

Path to the Firefox binary to use. By default geckodriver tries to find and use the system installation of Firefox, but that behaviour can be changed by using this option. Note that the binary capability of the moz:firefoxOptions object that is passed when creating a new session will override this option.

On Linux systems it will use the first firefox binary found by searching the PATH environmental variable, which is roughly equivalent to calling whereis(1) and extracting the second column:

% whereis firefox
firefox: /usr/bin/firefox /usr/local/firefox

On macOS, the binary is found by looking for the first firefox binary in the same fashion as on Linux systems. This means it is possible to also use PATH to control where geckodriver should find Firefox on macOS. It will then look for /Applications/Firefox.app.

On Windows systems, geckodriver looks for the system Firefox by scanning the Windows registry.

--connect-existing

Connect geckodriver to an existing Firefox instance. This means geckodriver will abstain from the default of starting a new Firefox session.

The existing Firefox instance must have Marionette enabled. To enable the remote protocol in Firefox, you can pass the --marionette flag. Unless the marionette.port preference has been user-set, Marionette will listen on port 2828. So when using --connect-existing it is likely you will also have to use --marionette-port to set the correct port.

--host HOST

Host to use for the WebDriver server. Defaults to 127.0.0.1.

--jsdebugger

Attach browser toolbox debugger when Firefox starts. This is useful for debugging Marionette internals.

To be prompted at the start of the test run or between tests, you can set the marionette.debugging.clicktostart preference to true.

For reference, below is the list of preferences that enables the chrome debugger. These are all set implicitly when the argument is passed to geckodriver.

  • devtools.browsertoolbox.panel -> jsdebugger

    Selects the Debugger panel by default.

  • devtools.chrome.enabled → true

    Enables debugging of chrome code.

  • devtools.debugger.prompt-connection → false

    Controls the remote connection prompt. Note that this will automatically expose your Firefox instance to localhost.

  • devtools.debugger.remote-enabled → true

    Allows a remote debugger to connect, which is necessary for debugging chrome code.

--log LEVEL

Set the Gecko and geckodriver log level. Possible values are fatal, error, warn, info, config, debug, and trace.

--log-no-truncate

Disables truncation of long log lines.

--marionette-host HOST

Selects the host for geckodriver’s connection to the Marionette remote protocol. Defaults to 127.0.0.1.

--marionette-port PORT

Selects the port for geckodriver’s connection to the Marionette remote protocol.

In the default mode where geckodriver starts and manages the Firefox process, it will pick a free port assigned by the system and set the marionette.port preference in the profile.

When --connect-existing is used and the Firefox process is not under geckodriver’s control, it will simply connect to PORT.

--connect-existing: #connect-existing

-p PORT / --port PORT

Port to use for the WebDriver server. Defaults to 4444.

A helpful trick is that it is possible to bind to 0 to get the system to atomically assign a free port.

--profile-root PROFILE_ROOT

Path to the directory to use when creating temporary profiles. By default this is the system temporary directory. Both geckodriver and Firefox must have read-write access to this path.

This setting can be useful when Firefox is sandboxed from the host filesystem such that it doesn’t share the same system temporary directory as geckodriver (e.g. when running Firefox inside a container or packaged as a snap).

-v[v]

Increases the logging verbosity by to debug level when passing a single -v, or to trace level if -vv is passed. This is analogous to passing --log debug and --log trace, respectively.

--websocket-portPORT

Port to use to connect to WebDriver BiDi. Defaults to 9222.

A helpful trick is that it is possible to bind to 0 to get the system to atomically assign a free port.