Skip to main content
The ChromeOptions class extends Selenium’s ChromiumOptions to provide additional functionality for configuring Chrome browser behavior in Undetected.

​
Basic Usage

import undetected as uc
from undetected import ChromeOptions

options = ChromeOptions()
options.add_argument("--start-maximized")
options.add_argument("--disable-notifications")

driver = uc.Chrome(options=options)
Custom options and arguments may trigger bot detection systems. Use with caution.

​
Configuration Methods

ChromeOptions inherits all standard Selenium ChromiumOptions methods: 
options = ChromeOptions()

# Add command-line arguments
options.add_argument("--window-size=1920,1080")
options.add_argument("--disable-blink-features=AutomationControlled")

# Set binary location
options.binary_location = "/path/to/chrome"

# Add extensions
options.add_extension("/path/to/extension.crx")

# Set experimental options
options.add_experimental_option("excludeSwitches", ["enable-automation"])
options.add_experimental_option("useAutomationExtension", False)

# Set preferences
options.add_experimental_option("prefs", {
    "download.default_directory": "/path/to/downloads",
    "download.prompt_for_download": False,
})

​
User Data Directory

The user_data_dir property provides a convenient way to set a Chrome profile directory. 
options = ChromeOptions()
options.user_data_dir = "/path/to/profile"

driver = uc.Chrome(options=options)
When you set user_data_dir:
  • The path is automatically normalized and converted to an absolute path
  • If the directory doesn’t exist, Chrome creates a new profile at that location
  • The profile persists after the driver quits (not automatically cleaned up)
Using ChromeOptions.user_data_dir is deprecated. Use Chrome(user_data_dir="/path") instead.

​
Preferences Handling

Undetected’s ChromeOptions includes special handling for Chrome preferences through the handle_prefs() method.

​
Dotted Key Notation

You can use dotted notation for nested preference keys: 
options = ChromeOptions()
options.add_experimental_option("prefs", {
    "profile.default_content_setting_values.notifications": 2,
    "download.default_directory": "/downloads",
    "download.prompt_for_download": False,
})
Undetected automatically converts dotted keys into nested dictionaries: 
# "profile.default_content_setting_values.notifications": 2
# becomes:
{
    "profile": {
        "default_content_setting_values": {
            "notifications": 2
        }
    }
}

​
Preference Merging

If a Preferences file already exists in the profile directory, Undetected merges your preferences with the existing ones, with your values taking precedence.

​
Creating Options from Existing Options

You can create a new ChromeOptions instance from an existing options object: 
existing_options = ChromeOptions()
existing_options.add_argument("--start-maximized")

# Create new options with same configuration
new_options = ChromeOptions.from_options(existing_options)

​
Common Configuration Examples

​
Disable Automation Indicators

options = ChromeOptions()
options.add_argument("--disable-blink-features=AutomationControlled")
options.add_experimental_option("excludeSwitches", ["enable-automation"])
options.add_experimental_option("useAutomationExtension", False)

​
Custom Download Directory

options = ChromeOptions()
options.add_experimental_option("prefs", {
    "download.default_directory": "/path/to/downloads",
    "download.prompt_for_download": False,
    "download.directory_upgrade": True,
})

​
Disable Notifications

options = ChromeOptions()
options.add_experimental_option("prefs", {
    "profile.default_content_setting_values.notifications": 2
})

​
Custom User Agent

options = ChromeOptions()
options.add_argument("--user-agent=Mozilla/5.0 (Windows NT 10.0; Win64; x64)...")

​
Proxy Configuration

options = ChromeOptions()
options.add_argument("--proxy-server=http://proxy.example.com:8080")

​
Disable Images for Faster Loading

options = ChromeOptions()
options.add_experimental_option("prefs", {
    "profile.managed_default_content_settings.images": 2
})

​
Important Notes

ChromeOptions objects cannot be reused. Creating multiple Chrome instances with the same options object will raise a RuntimeError:
options = ChromeOptions()
driver1 = uc.Chrome(options=options)  # OK
driver2 = uc.Chrome(options=options)  # RuntimeError!
Create a new ChromeOptions instance for each Chrome driver.
The Chrome class automatically sets many options for optimal undetectability. Only add custom options if absolutely necessary, as they may interfere with stealth features.

​
Automatic Options

Even when you don’t provide options, Undetected automatically sets several arguments:
  • --remote-debugging-host=127.0.0.1
  • --remote-debugging-port=<auto>
  • --window-size=1920,1080
  • --start-maximized
  • --no-sandbox
  • --no-default-browser-check
  • --no-first-run
  • --lang=<system-locale>
  • --log-level=0
These are carefully chosen to balance functionality and undetectability.