Skip to main content
The Config class controls browser launch parameters, behavior, and Chrome command-line arguments. It provides a flexible way to customize your browser automation setup.

​
Creating a configuration

You can create a Config object explicitly or let the browser create one automatically: 
from nodriver import Config, Browser

# Create config explicitly
config = Config(
    headless=False,
    browser_executable_path='/path/to/chrome',
    user_data_dir='./my-profile'
)

browser = await Browser.create(config=config)

# Or pass parameters directly to Browser.create()
browser = await Browser.create(
    headless=False,
    sandbox=True
)
When you don’t provide a Config object, nodriver creates one with sensible defaults automatically.

​
Configuration parameters

​
User data directory

Specify where browser profile data is stored:
​
user_data_dir
PathLike
default:"AUTO"
Path to the browser profile directory. If not specified, a temporary directory is created and cleaned up on exit.
config = Config(user_data_dir='/path/to/profile')
Use cases:
  • Persist cookies and login sessions between runs
  • Maintain browser extensions
  • Store cached data
When you provide a custom user_data_dir, it will NOT be automatically deleted. When using the auto-generated directory, it’s cleaned up when the browser closes.

​
Headless mode

​
headless
bool
default:"False"
Run the browser without a visible window. Uses the new --headless=new flag.
# Headless mode
config = Config(headless=True)

# Visible browser (default)
config = Config(headless=False)
When to use headless:
  • Server environments without displays
  • Automated testing pipelines
  • Background scraping tasks
  • When you don’t need visual feedback
Some websites detect headless browsers. nodriver automatically patches the user agent to remove “Headless” markers, but detection may still occur.

​
Browser executable

​
browser_executable_path
PathLike
default:"AUTO"
Path to the Chrome/Chromium executable. Auto-detected if not provided.
config = Config(
    browser_executable_path='/usr/bin/google-chrome-stable'
)
The auto-detection searches for:
  • Google Chrome
  • Chromium
  • Chrome Beta
  • Chrome Canary
Detection paths: Linux/macOS:
  • /usr/bin/google-chrome
  • /usr/bin/chromium
  • /Applications/Google Chrome.app/Contents/MacOS/Google Chrome (macOS)
Windows:
  • C:\Program Files\Google\Chrome\Application\chrome.exe
  • C:\Program Files (x86)\Google\Chrome\Application\chrome.exe

​
Browser arguments

​
browser_args
List[str]
default:"AUTO"
Additional command-line arguments passed to Chrome.
config = Config(
    browser_args=[
        '--window-size=1920,1080',
        '--start-maximized',
        '--disable-gpu'
    ]
)
You can also add arguments after creation: 
config = Config()
config.add_argument('--window-size=1920,1080')
config.add_argument('--disable-gpu')
Some arguments are managed by Config properties and should not be added manually:
  • --headless (use headless parameter)
  • --user-data-dir (use user_data_dir parameter)
  • --no-sandbox (use sandbox parameter)
  • --lang (use lang parameter)

​
Sandbox mode

​
sandbox
bool
default:"True"
Enable Chrome’s sandbox for security. Automatically disabled when running as root on Linux.
# Disable sandbox (sometimes needed in Docker)
config = Config(sandbox=False)
On Linux systems, if you’re running as root, sandbox is automatically disabled even if you set sandbox=True.

​
Language

​
lang
str
default:"'en-US'"
Browser language setting.
config = Config(lang='de-DE')

​
Connection settings

​
host
str
default:"AUTO"
Host for the DevTools Protocol connection. Defaults to “127.0.0.1” when starting a new browser.
​
port
int
default:"AUTO"
Port for the DevTools Protocol connection. Auto-assigned to a free port when starting a new browser.
# Connect to existing Chrome instance
config = Config(
    host='127.0.0.1',
    port=9222
)
When both host and port are specified, nodriver connects to an existing browser instead of launching a new one.

​
Expert mode

​
expert
bool
default:"AUTO"
Enable expert mode with additional debugging capabilities.
config = Config(expert=True)
Expert mode includes:
  • --disable-site-isolation-trials flag
  • Ensures shadow roots are always in “open” mode
  • Additional debugging scripts
Expert mode is useful for development and debugging but may affect page behavior.

​
Target discovery

​
autodiscover_targets
bool
default:"True"
Automatically discover and track new browser targets (tabs, windows, iframes).
config = Config(autodiscover_targets=True)
This enables automatic updates when:
  • New tabs are opened
  • Windows are created
  • Tabs are closed
  • Target information changes

​
Default browser arguments

nodriver includes sensible defaults that are always applied: 
--remote-allow-origins=*       # Allow DevTools connections
--no-first-run                 # Skip first run dialogs
--no-service-autorun           # Disable service auto-run
--no-default-browser-check     # Skip default browser check
--homepage=about:blank         # Start with blank page
--no-pings                     # Disable hyperlink auditing
--password-store=basic         # Use basic password store
--disable-infobars             # Hide infobars
--disable-breakpad             # Disable crash reporting
--disable-dev-shm-usage        # Fix shared memory issues
--disable-session-crashed-bubble
--disable-search-engine-choice-screen

​
Extensions

Load browser extensions: 
config = Config()
config.add_extension('/path/to/extension')
config.add_extension('/path/to/extension.crx')
​
extension_path
PathLike
required
Path to extension folder (containing manifest.json) or .crx file.
# Load extension from folder
config.add_extension('./my-extension')

# Load from .crx file (auto-extracted)
config.add_extension('./my-extension.crx')

​
Inspecting configuration

Get the final list of arguments: 
config = Config(headless=True, sandbox=False)
args = config()  # Returns list of all arguments

for arg in args:
    print(arg)
View configuration details: 
config = Config(headless=True)
print(config)
Output: 
Config
    browser_executable_path = /usr/bin/google-chrome
    headless = True
    sandbox = False
    host = None
    port = None
    ...

​
Utility functions

​
Find Chrome executable

Manually find Chrome installation: 
from nodriver.config import find_chrome_executable

chrome_path = find_chrome_executable()
print(f"Chrome found at: {chrome_path}")

# Get all found installations
all_chrome = find_chrome_executable(return_all=True)

​
Create temporary profile

Generate a temp directory path: 
from nodriver.config import temp_profile_dir

temp_dir = temp_profile_dir()
print(f"Temp profile: {temp_dir}")

​
Check if root

from nodriver.config import is_root

if is_root():
    print("Running as root, sandbox will be disabled")

​
Platform detection

from nodriver.config import is_posix

if is_posix:
    print("Running on Unix-like system")
else:
    print("Running on Windows")

​
Common configurations

​
Development setup

config = Config(
    headless=False,
    user_data_dir='./dev-profile',
    expert=True,
    browser_args=['--auto-open-devtools-for-tabs']
)

​
Production scraping

config = Config(
    headless=True,
    sandbox=True,
    browser_args=[
        '--disable-gpu',
        '--disable-dev-shm-usage',
        '--disable-software-rasterizer'
    ]
)

​
Docker environment

config = Config(
    headless=True,
    sandbox=False,  # Required in most Docker setups
    browser_args=[
        '--disable-dev-shm-usage',
        '--disable-gpu',
        '--no-first-run',
        '--no-zygote',
        '--single-process'  # May be needed in constrained environments
    ]
)

​
With persistent profile

config = Config(
    user_data_dir='./persistent-profile',
    headless=False
)

​
Connect to remote browser

# On remote machine, start Chrome with:
# chrome --remote-debugging-port=9222 --remote-debugging-address=0.0.0.0

config = Config(
    host='192.168.1.100',
    port=9222
)

​
Best practices

When you need to maintain login state across runs:
config = Config(user_data_dir='./saved-profile')
The first run will be clean, but subsequent runs will have cookies, cache, and local storage preserved.
The sandbox provides security isolation. Only disable it when:
  • Running in Docker containers
  • Running as root (automatically disabled)
  • Encountering sandbox-related crashes
Begin with default configuration and add arguments only when needed. Too many arguments can cause conflicts or unexpected behavior.
Some websites behave differently in headless mode. Test both modes to ensure compatibility.
Each extension increases resource usage and may affect page behavior. Only load necessary extensions.

​
Troubleshooting

​
Browser won’t start

# Try disabling sandbox
config = Config(sandbox=False)

​
Chrome not found

# Specify path explicitly
config = Config(
    browser_executable_path='/path/to/chrome'
)

​
Connection refused

# Ensure port is free or let it auto-assign
config = Config(port=None)  # Auto-assign

​
Out of memory in Docker

config = Config(
    headless=True,
    sandbox=False,
    browser_args=[
        '--disable-dev-shm-usage',
        '--disable-gpu',
        '--no-zygote'
    ]
)

Build docs developers (and LLMs) love

Get started for freeTalk to us