Capabilities and ChromeOptions

Capabilities are options that you can use to customize and configure a ChromeDriver session. This page documents all ChromeDriver supported capabilities and how to use them.

The WebDriver language APIs provides ways to pass capabilities to ChromeDriver. The exact mechanism differs by the language, but most languages use one or both of the following mechanisms:

1. Use the ChromeOptions class. This is supported by Java, Python, etc.
2. Use the DesiredCapabilities class. This is supported by Python, Ruby, etc. While it's also available in Java, its usage in Java is deprecated.

Using the ChromeOptions class

You can create an instance of ChromeOptions, which has convenient methods for setting ChromeDriver-specific capabilities. You can then pass the ChromeOptions object into the ChromeDriver constructor:

ChromeOptions options = new ChromeOptions();
options.addExtensions(new File("/path/to/extension.crx"));
ChromeDriver driver = new ChromeDriver(options);

Since Selenium version 3.6.0, the ChromeOptions class in Java also implement the Capabilities interface, allowing you to specify other WebDriver capabilities not specific to ChromeDriver.

ChromeOptions options = new ChromeOptions();

// Add the WebDriver proxy capability.
Proxy proxy = new Proxy();
proxy.setHttpProxy("myhttpproxy:3337");
options.setCapability("proxy", proxy);

// Add a ChromeDriver-specific capability.
options.addExtensions(new File("/path/to/extension.crx"));
ChromeDriver driver = new ChromeDriver(options);

Use DesiredCapabilities

To use DesiredCapabilities, you need to know the name of the capability and the type of value it takes. See the full list.

Python

caps = webdriver.DesiredCapabilities.CHROME.copy()
caps['acceptInsecureCerts'] = True
driver = webdriver.Chrome(desired_capabilities=caps)

Ruby

caps = Selenium::WebDriver::Remote::Capabilities.chrome(
  "goog:chromeOptions" => {"args" => [ "window-size=1000,800" ]})
driver = Selenium::WebDriver.for :chrome, desired_capabilities: caps

Common use cases

Use a custom profile

By default, ChromeDriver creates a new temporary profile for each session. You may want to set special preferences or just use a custom profile altogether, also called the user data directory.

If using the temporary profile, you can use the chrome.prefs capability to specify preferences to apply after Chrome starts. For custom profiles, you can use the user-data-dir Chrome command-line switch to tell Chrome which profile to use:

ChromeOptions options = new ChromeOptions();
options.addArguments("user-data-dir=/path/to/your/custom/profile");

Create your own custom profile by running Chrome on the command-line or with ChromeDriver, using the user-data-dir switch set to some new directory.

If the path doesn't exist, Chrome creates a new profile in the specified location. You can then modify the profile settings, and ChromeDriver can use the profile in the future. Open chrome://version in the browser to see what profile Chrome is using.

Start Chrome maximized

Start Chrome maximized by using the start-maximized switch:

ChromeOptions options = new ChromeOptions();
options.addArguments("start-maximized");

Use a Chrome executable in a non-standard location

ChromeOptions options = new ChromeOptions();
options.setBinary("/path/to/other/chrome/binary");

Block dialog windows

By default, ChromeDriver configures Chrome to allow pop-up windows. If you want to block pop-ups, and restore the normal Chrome behavior when it isn't controlled by ChromeDriver, do the following:

ChromeOptions options = new ChromeOptions();
options.setExperimentalOption("excludeSwitches",
     Arrays.asList("disable-popup-blocking"));

Set download directory

The following code can be used to configure Chrome to download files to a specific directory. However, there are several caveats to be aware of:

• Chrome disallows using certain directories for download. In particular, you cannot use the desktop folder as the download directory. On Linux, you cannot use the home directory for download. The exact list of forbidden directories is subject to change, so we recommended that you use a unique directory that has no special meaning to the system.
• ChromeDriver does not automatically wait for download to complete. If you call driver.quit() too soon, Chrome might terminate before the download has finished.
• For best results, use full paths, as relative paths don't always work.
• On Windows, use \` as path separators./` isn't reliable on Windows.

ChromeOptions options = new ChromeOptions();
Map<String, Object> prefs = new HashMap<String, Object>();
prefs.put("download.default_directory", "/directory/path");
options.setExperimentalOption("prefs", prefs);

Recognized capabilities

Read the Selenium documentation and W3C WebDriver standard for standard capabilities accepted by ChromeDriver. Here, we list the Chrome-specific capabilities.

ChromeOptions object

Most Chrome-specific capabilities are exposed through the ChromeOptions object. In some languages, they're implemented by the ChromeOptions class. In other languages, they're stored under the goog:chromeOptions dictionary in selected capabilities.

perfLoggingPrefs object

The perfLoggingPrefs dictionary has the following format. All keys are optional:

Returned Capabilities

Here's a list of all the Chrome-specific returned capabilities, in other words, what ChromeDriver returns when you create a new session.