Skip to content

API reference

playwright_byob

Bring your own browser to Playwright.

ChromeLaunchConfig dataclass

Resolved arguments for chromium.launch_persistent_context.

user_data_dir is passed as the first positional argument. options is expanded as keyword arguments.

to_playwright_kwargs()

Return a mutable copy of the keyword arguments for Playwright.

ChromeNotFoundError

Bases: PlaywrightByobError

Raised when a requested Chrome executable cannot be found.

ChromeProfileInUseError

Bases: PlaywrightByobError

Raised when the Chrome user data directory appears to be locked.

ChromeProfileNotFoundError

Bases: PlaywrightByobError

Raised when a requested Chrome user data directory cannot be found.

ChromeRemoteDebuggingBlockedError

Bases: ConfigurationError

Raised when Chrome blocks remote debugging for the selected profile root.

ConfigurationError

Bases: PlaywrightByobError, ValueError

Raised when launch configuration is invalid.

PlaywrightByobError

Bases: RuntimeError

Base exception for playwright-byob failures.

async_launch_chrome(playwright, *, browser_path='auto', user_data_dir='auto', profile_directory='auto', channel=DEFAULT_CHANNEL, headless=False, args=None, default_args=True, ignore_default_args=DEFAULT_IGNORE_DEFAULT_ARGS, no_viewport=True, check_profile_lock=True, **launch_options) async

Launch an async persistent context with installed Chrome.

By default, the context uses playwright-byob's dedicated non-default Chrome user data directory, not the platform default Chrome profile root.

build_chrome_launch_config(*, browser_path='auto', user_data_dir='auto', profile_directory='auto', channel=DEFAULT_CHANNEL, headless=False, args=None, default_args=True, ignore_default_args=DEFAULT_IGNORE_DEFAULT_ARGS, no_viewport=True, check_profile_lock=True, sys_platform=None, env=None, **launch_options)

Build resolved launch parameters for Playwright's persistent context.

Defaults are intentionally tuned for using installed Google Chrome in headed mode with a persistent, non-default automation profile:

  • use the installed Chrome executable;
  • use a package-owned Chrome user data directory under the platform app data directory;
  • select the Default Chrome profile directory;
  • run headed with Playwright's fixed viewport disabled;
  • hide Playwright's --enable-automation default argument.

Extra launch_options are passed directly to Playwright and can override most defaults. Use args for additional Chrome flags, or set default_args=False to opt out of this package's default Chrome flags. Set browser_path=None to skip Chrome executable detection and ask Playwright to use channel instead. Set check_profile_lock=False to skip the best-effort check for Chrome profile lock artifacts.

Chrome 136 and newer ignore Playwright's remote debugging pipe when the user data directory is Chrome stable's platform default profile root. This function raises ChromeRemoteDebuggingBlockedError for that configuration before Playwright starts Chrome.

chrome_executable_candidates(*, sys_platform=None, env=None)

Return plausible Google Chrome executable paths for the current platform.

The function only builds candidates; it does not read profile data or launch Chrome. The PLAYWRIGHT_BYOB_CHROME_PATH environment variable, when set, is returned first.

chrome_user_data_dir_candidates(*, sys_platform=None, env=None)

Return configured and platform default Google Chrome user data directories.

PLAYWRIGHT_BYOB_USER_DATA_DIR is returned first when set. Platform defaults follow, such as .../Google/Chrome on macOS or .../Google/Chrome/User Data on Windows. They may contain profile folders named Default, Profile 1, and so on. This function is exposed for detection and migration code; launch defaults use a separate automation directory.

detect_chrome_executable(browser_path='auto', *, sys_platform=None, env=None)

Return an existing Google Chrome executable, or None if not found.

Pass browser_path to check one explicit path. With the default "auto", common platform locations and PLAYWRIGHT_BYOB_CHROME_PATH are checked.

detect_chrome_user_data_dir(user_data_dir='auto', *, sys_platform=None, env=None)

Return an existing Google Chrome user data directory, or None.

launch_chrome(playwright, *, browser_path='auto', user_data_dir='auto', profile_directory='auto', channel=DEFAULT_CHANNEL, headless=False, args=None, default_args=True, ignore_default_args=DEFAULT_IGNORE_DEFAULT_ARGS, no_viewport=True, check_profile_lock=True, **launch_options)

Launch a sync Playwright persistent context with installed Chrome.

By default, the context uses playwright-byob's dedicated non-default Chrome user data directory, not the platform default Chrome profile root.

Example 
from playwright.sync_api import sync_playwright
from playwright_byob import launch_chrome

with sync_playwright() as p:
    context = launch_chrome(p)
    page = context.new_page()
    page.goto("https://example.com")
    context.close()