Config

Configure browser launch parameters and behavior

Overview

The Config class encapsulates all browser configuration options. You can create a Config object to customize browser behavior, or pass parameters directly to start() or Browser.create().

Calling a Config instance (e.g., config()) returns the list of command-line arguments that will be passed to the browser.

Constructor

def __init__(
    self,
    user_data_dir: Optional[PathLike] = None,
    headless: Optional[bool] = False,
    browser_executable_path: Optional[PathLike] = None,
    browser_args: Optional[List[str]] = None,
    sandbox: Optional[bool] = True,
    lang: Optional[str] = "en-US",
    host: str = None,
    port: int = None,
    expert: bool = None,
    **kwargs: dict,
)

Parameters

user_data_dir · PathLike · default: "None"

Path to the user data directory. If not specified, a temporary directory is created and deleted on exit.

headless · bool · default: "False"

Run browser in headless mode (no visible window).

browser_executable_path · PathLike · default: "None"

Path to the browser executable. If not specified, nodriver will auto-detect Chrome/Chromium.

browser_args · List[str] · default: "None"

Additional command-line arguments to pass to the browser.

sandbox · bool · default: "True"

Enable sandbox mode. When False, adds --no-sandbox. Automatically disabled when running as root on Linux.

lang · str · default: "en-US"

Browser language setting.

host · str · default: "None"

Host for remote debugging. When both host and port are set, connects to existing browser instead of launching new one.

port · int · default: "None"

Port for remote debugging. When both host and port are set, connects to existing browser instead of launching new one.

expert · bool · default: "None"

Enable expert mode with additional debugging features and reduced security restrictions.

**kwargs · dict · default: "None"

Additional keyword arguments are stored as attributes on the Config object.

Properties

browser_args · List[str]

Returns the complete list of browser arguments (default args + custom args).

user_data_dir · str

Path to the user data directory.

uses_custom_data_dir · bool

Whether a custom user data directory was specified (True) or a temporary one was created (False).

browser_executable_path · str

Path to the browser executable.

headless · bool

Whether running in headless mode.

sandbox · bool

Whether sandbox is enabled.

lang · str

Browser language setting.

host · str

Remote debugging host.

port · int

Remote debugging port.

expert · bool

Whether expert mode is enabled.

Methods

add_argument()

Add a custom browser argument.

def add_argument(self, arg: str)

arg · str · required

Browser argument to add (e.g., “—disable-gpu”).

Cannot add arguments related to headless, data-dir, sandbox, or lang. Use Config properties instead.

Example:

config = Config()
config.add_argument('--disable-gpu')
config.add_argument('--window-size=1920,1080')

add_extension()

Add a Chrome extension to load.

def add_extension(self, extension_path: PathLike)

extension_path · PathLike · required

Path to extension folder (containing manifest) or .crx file.

Example:

config = Config()
config.add_extension('/path/to/extension/folder')
config.add_extension('/path/to/extension.crx')

browser = await Browser.create(config)

call()

Get the list of browser arguments.

def __call__(self) -> List[str]

Returns: Complete list of command-line arguments to pass to the browser.

Example:

config = Config(headless=True)
args = config()
print(args)
# ['--remote-allow-origins=*', '--no-first-run', ..., '--headless=new']

Default Browser Arguments

The Config class automatically includes these default arguments:

• --remote-allow-origins=* - Allow remote connections
• --no-first-run - Skip first run wizards
• --no-service-autorun - Disable service auto-run
• --no-default-browser-check - Skip default browser check
• --homepage=about:blank - Set homepage to blank
• --no-pings - Disable hyperlink auditing
• --password-store=basic - Use basic password store
• --disable-infobars - Disable info bars
• --disable-breakpad - Disable crash reporter
• --disable-dev-shm-usage - Disable /dev/shm usage
• --disable-session-crashed-bubble - Disable crash bubble
• --disable-search-engine-choice-screen - Skip search engine choice

Examples

Basic configuration

import nodriver as uc
from nodriver import Config

async def main():
    # Create config
    config = Config(
        headless=True,
        lang='en-US'
    )
    
    # Launch with config
    browser = await uc.start(config)
    tab = await browser.get('https://example.com')
    
    browser.stop()

uc.loop().run_until_complete(main())

Custom user data directory

import nodriver as uc
from nodriver import Config

async def main():
    # Use persistent profile
    config = Config(
        user_data_dir='/path/to/chrome/profile'
    )
    
    browser = await uc.start(config)
    tab = await browser.get('https://example.com')
    
    # Cookies and settings will persist
    browser.stop()

uc.loop().run_until_complete(main())

Advanced configuration

import nodriver as uc
from nodriver import Config

async def main():
    config = Config(
        headless=False,
        browser_args=[
            '--window-size=1920,1080',
            '--disable-blink-features=AutomationControlled',
        ],
        expert=True
    )
    
    # Add more arguments
    config.add_argument('--disable-gpu')
    
    # Add extension
    config.add_extension('/path/to/extension')
    
    browser = await uc.start(config)
    tab = await browser.get('https://example.com')
    
    browser.stop()

uc.loop().run_until_complete(main())

Connect to existing browser

import nodriver as uc
from nodriver import Config

async def main():
    # First, launch Chrome manually with:
    # chrome --remote-debugging-port=9222
    
    config = Config(
        host='127.0.0.1',
        port=9222
    )
    
    # Connect to existing browser
    browser = await uc.start(config)
    
    # Control existing tabs
    for tab in browser.tabs:
        print(f"Tab URL: {tab.url}")

uc.loop().run_until_complete(main())

Expert mode for testing

import nodriver as uc
from nodriver import Config

async def main():
    # Expert mode enables:
    # - Disabled web security for cross-origin access
    # - Disabled site isolation
    # - Shadow roots forced to open mode
    config = Config(
        expert=True,
        headless=False
    )
    
    browser = await uc.start(config)
    tab = await browser.get('https://example.com')
    
    # Shadow DOM elements will be accessible
    browser.stop()

uc.loop().run_until_complete(main())

Multiple browser instances

import nodriver as uc
from nodriver import Config
import asyncio

async def create_browser_instance(profile_dir, port):
    config = Config(
        user_data_dir=profile_dir,
        port=port
    )
    return await uc.start(config)

async def main():
    # Launch multiple isolated browser instances
    browser1 = await create_browser_instance('/tmp/profile1', 9222)
    browser2 = await create_browser_instance('/tmp/profile2', 9223)
    
    tab1 = await browser1.get('https://example.com')
    tab2 = await browser2.get('https://example.org')
    
    await asyncio.sleep(5)
    
    browser1.stop()
    browser2.stop()

uc.loop().run_until_complete(main())

Utility Functions

find_chrome_executable()

Find Chrome/Chromium executable on the system.

from nodriver.core.config import find_chrome_executable

# Get path to Chrome
chrome_path = find_chrome_executable()
print(chrome_path)

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

temp_profile_dir()

Generate a temporary profile directory path.

from nodriver.core.config import temp_profile_dir

temp_dir = temp_profile_dir()
print(temp_dir)  # e.g., /tmp/uc_abc123

is_root()

Check if running as root/administrator.

from nodriver.core.config import is_root

if is_root():
    print("Running as root")

Notes

When running as root on Linux, sandbox is automatically disabled as Chrome requires this to start.

Temporary user data directories are automatically cleaned up when the browser stops.

Expert mode reduces security restrictions and should only be used for testing and development.

See also

• start() - Launch browser with configuration
• Browser.create() - Create browser instance