Profiles

geckodriver uses profiles to instrument Firefox’ behaviour. The user will usually rely on geckodriver to generate a temporary, throwaway profile. These profiles are deleted when the WebDriver session expires.

In cases where the user needs to use custom, prepared profiles, geckodriver will make modifications to the profile that ensures correct behaviour. See Automation preferences below on the precedence of user-defined preferences in this case.

Custom profiles can be provided two different ways:

  1. by appending --profile /some/location to the args capability, which will instruct geckodriver to use the profile in-place;

  2. or by setting the profile capability to a Base64-encoded ZIP of the profile directory.

Note that geckodriver has a known bug concerning --profile that prevents the randomised Marionette port from being passed to geckodriver. To circumvent this issue, make sure you specify the port manually using --marionette-port <port>.

The second way is compatible with shipping Firefox profiles across a network, when for example the geckodriver instance is running on a remote system. This is the case when using Selenium’s RemoteWebDriver concept, where the WebDriver client and the server are running on two distinct systems.

Default locations for temporary profiles

When a custom user profile is not provided with the -profile command-line argument geckodriver generates a temporary, throwaway profile. This is written to the default system temporary folder and subsequently removed when the WebDriver session expires.

The default location for temporary profiles depends on the system. On Unix systems it uses /tmp, and on Windows it uses the Windows directory.

The default location can be overridden. On Unix you set the TMPDIR environment variable. On Windows, the following environment variables are respected, in order:

  1. TMP

  2. TEMP

  3. USERPROFILE

It is not necessary to change the temporary directory system-wide. All you have to do is make sure it gets set for the environment of the geckodriver process:

TMPDIR=/some/location ./geckodriver

Automation preferences

As indicated in the introduction, geckodriver configures Firefox so it is well-behaved in automation environments. It uses a combination of preferences written to the profile prior to launching Firefox (1), and a set of recommended preferences set on startup (2).

These can be perused here:

  1. testing/geckodriver/src/prefs.rs

  2. remote/components/marionette.js

As mentioned, these are recommended preferences, and any user-defined preferences in the user.js file or as part of the prefs capability take precedence. This means for example that the user can tweak browser.startup.page to override the recommended preference for starting the browser with a blank page.

The recommended preferences set at runtime (see 2 above) may also be disabled entirely by setting remote.prefs.recommended starting with Firefox 91. For older versions of Firefox, the preference to use was marionette.prefs.recommended. This may however cause geckodriver to not behave correctly according to the WebDriver standard, so it should be used with caution.

Users should take note that the marionette.port preference is special, and will always be overridden when using geckodriver unless the --marionette-port <port> flag is used specifically to instruct the Marionette server in Firefox which port to use.

Temporary profiles not being removed

It is a known bug that geckodriver in some instances fails to remove the temporary profile, particularly when the session is not explicitly deleted or the process gets interrupted. See geckodriver issue 299 for more information.