Skip to main content

​
Overview

The start() function is the main entry point for launching a browser with nodriver. You can call it without any parameters to quickly launch a browser instance with best practice defaults.
This is an async function and must be called with await start()

​
Signature

async def start(
    config: Optional[Config] = None,
    *,
    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] = None,
    host: Optional[str] = None,
    port: Optional[int] = None,
    expert: Optional[bool] = None,
    **kwargs: Optional[dict],
) -> Browser

​
Parameters

​
config
Config
default:"None"
Configuration object. If provided, other parameters are ignored.
​
user_data_dir
PathLike
default:"None"
Path to the user data directory. If not specified, a temporary directory is created.
​
headless
bool
default:"False"
Run browser in headless mode. Set to True to run without a visible window.
​
browser_executable_path
PathLike
default:"None"
Path to the browser executable. If not specified, nodriver will auto-detect the Chrome/Chromium installation.
​
browser_args
List[str]
default:"None"
Additional browser arguments to pass to Chrome. Format: ["--some-param=value", "--other-param=value"]
​
sandbox
bool
default:"True"
Enable or disable sandbox mode. When False, adds --no-sandbox to browser arguments. On Linux as root user, this is automatically set to False.
​
lang
str
default:"None"
Language string for the browser (e.g., “en-US”).
​
host
str
default:"None"
Host for remote debugging connection. If both host and port are provided, nodriver connects to an existing browser instead of launching a new one.
​
port
int
default:"None"
Port for remote debugging connection. If both host and port are provided, nodriver connects to an existing browser instead of launching a new one.
​
expert
bool
default:"None"
Enable expert mode. When True, includes --disable-web-security and --disable-site-isolation-trials parameters, and enables debugging features like forcing shadow roots to open mode.
​
**kwargs
dict
default:"None"
Additional keyword arguments passed to the Config object.

​
Returns

​
Browser
Browser
A Browser instance ready to control tabs and navigate to URLs.

​
Examples

​
Basic usage

import nodriver as uc

async def main():
    # Launch with default settings
    browser = await uc.start()
    
    # Navigate to a URL
    tab = await browser.get('https://example.com')
    
    # Clean up
    browser.stop()

if __name__ == '__main__':
    uc.loop().run_until_complete(main())

​
Headless mode

import nodriver as uc

async def main():
    # Launch in headless mode
    browser = await uc.start(headless=True)
    tab = await browser.get('https://example.com')
    
    # Take a screenshot
    await tab.save_screenshot('screenshot.png')
    browser.stop()

if __name__ == '__main__':
    uc.loop().run_until_complete(main())

​
Custom browser arguments

import nodriver as uc

async def main():
    # Launch with custom arguments
    browser = await uc.start(
        browser_args=[
            '--window-size=1920,1080',
            '--disable-extensions'
        ]
    )
    tab = await browser.get('https://example.com')
    browser.stop()

if __name__ == '__main__':
    uc.loop().run_until_complete(main())

​
Connect to existing browser

import nodriver as uc

async def main():
    # Connect to existing Chrome instance running with remote debugging
    # Start Chrome with: chrome --remote-debugging-port=9222
    browser = await uc.start(host='127.0.0.1', port=9222)
    tab = await browser.get('https://example.com')

if __name__ == '__main__':
    uc.loop().run_until_complete(main())

​
Expert mode

import nodriver as uc

async def main():
    # Launch with expert mode for advanced debugging
    browser = await uc.start(expert=True)
    tab = await browser.get('https://example.com')
    
    # Shadow roots will be forced to open mode
    # Web security is disabled for cross-origin access
    browser.stop()

if __name__ == '__main__':
    uc.loop().run_until_complete(main())

​
Notes

When running as root on Linux, the sandbox is automatically disabled. This is required for Chrome to start.
If you provide both host and port, nodriver will connect to an existing browser instance instead of launching a new one.

​
See also

  • Browser class - The Browser object returned by start()
  • Config class - Configuration object for advanced usage
  • loop() - Create an event loop for running async code

Build docs developers (and LLMs) love

Get started for freeTalk to us