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
Path to the user data directory. If not specified, a temporary directory is created and deleted on exit.
Run browser in headless mode (no visible window).
Path to the browser executable. If not specified, nodriver will auto-detect Chrome/Chromium.
Additional command-line arguments to pass to the browser.
Enable sandbox mode. When False, adds --no-sandbox. Automatically disabled when running as root on Linux.
Browser language setting.
Host for remote debugging. When both host and port are set, connects to existing browser instead of launching new one.
Port for remote debugging. When both host and port are set, connects to existing browser instead of launching new one.
Enable expert mode with additional debugging features and reduced security restrictions.
Additional keyword arguments are stored as attributes on the Config object.
Properties
Returns the complete list of browser arguments (default args + custom args).
Path to the user data directory.
Whether a custom user data directory was specified (True) or a temporary one was created (False).
Path to the browser executable.
Whether running in headless mode.
Whether sandbox is enabled.
Browser language setting.
Whether expert mode is enabled.
Methods
add_argument()
Add a custom browser argument.
def add_argument(self, arg: str)
Browser argument to add (e.g., “—disable-gpu”).
Cannot add arguments related to headless, data-dir, sandbox, or lang. Use Config properties instead.
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)
Path to extension folder (containing manifest) or .crx file.
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]
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