{"id":7056,"library":"browserstack-local","title":"BrowserStack Local Python","description":"The `browserstack-local` Python library provides bindings for the BrowserStack Local testing feature. It allows users to test websites hosted on local development environments, staging environments, or behind firewalls/proxies, by establishing a secure tunnel between the user's machine and the BrowserStack cloud. The library is currently at version 1.2.14 and maintains an active development status with a positive release cadence, often releasing new versions within three months.","status":"active","version":"1.2.14","language":"en","source_language":"en","source_url":"https://github.com/browserstack/browserstack-local-python","tags":["BrowserStack","Local","selenium","testing","tunnel"],"install":[{"cmd":"pip install browserstack-local","lang":"bash","label":"Install with pip"}],"dependencies":[],"imports":[{"symbol":"Local","correct":"from browserstack.local import Local"}],"quickstart":{"code":"import os\nfrom browserstack.local import Local\n\nbs_local = Local()\n\n# Replace <browserstack-accesskey> with your key or set as environment variable BROWSERSTACK_ACCESS_KEY\naccess_key = os.environ.get('BROWSERSTACK_ACCESS_KEY', 'YOUR_BROWSERSTACK_ACCESS_KEY')\n\nbs_local_args = {\n    \"key\": access_key,\n    \"verbose\": \"true\" # Optional: enable verbose logging\n}\n\ntry:\n    # Start the Local instance\n    bs_local.start(**bs_local_args)\n    print(\"BrowserStack Local started.\")\n\n    # Check if BrowserStack Local instance is running\n    if bs_local.isRunning():\n        print(\"BrowserStack Local is running.\")\n        # Your test logic here that uses the local tunnel\n    else:\n        print(\"BrowserStack Local is NOT running.\")\n\nfinally:\n    # Stop the Local instance\n    if bs_local.isRunning():\n        bs_local.stop()\n        print(\"BrowserStack Local stopped.\")","lang":"python","description":"This example demonstrates how to initialize, start, check the status of, and stop a BrowserStack Local tunnel. It uses an environment variable for the BrowserStack Access Key, which is the recommended practice for security. The `verbose` option is added for detailed logging."},"warnings":[{"fix":"Ensure stable internet connectivity and appropriate firewall/proxy settings. From v1.2.1, the library attempts to re-download corrupt binaries. Manually delete the binary (often in a temporary directory) to force a fresh download if issues persist.","message":"Binary download issues or corruption: The `browserstack-local` library automatically downloads and manages the underlying BrowserStack Local binary. Network issues, restrictive firewalls, or insufficient file permissions can prevent successful download or corrupt the binary, leading to connection failures.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure each concurrent local connection uses a unique `localIdentifier` argument. Alternatively, use the `force: true` option to automatically terminate other running instances when starting a new one.","message":"Multiple Local instances: Running multiple instances of BrowserStack Local without unique `localIdentifier`s will cause older connections to drop, leading to unstable tests or connection failures.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure `binary_path` points to a valid and accessible BrowserStack Local binary. If you encounter issues, consider removing this option and letting the library manage the binary automatically.","message":"Incorrect `binary_path` option: While `v1.2.2` addressed issues with the `binary_path` option, incorrectly configuring it or pointing to an inaccessible path can still prevent the local tunnel from starting.","severity":"gotcha","affected_versions":"<1.2.2 (buggy), all versions (user error)"},{"fix":"Upgrade to `browserstack-local` version `1.1.0` or newer to ensure reliable environment variable processing for your access key.","message":"Environment variable for access key: Prior to `v1.1.0`, there were known issues with environment variable handling for the `BROWSERSTACK_ACCESS_KEY`, which could lead to authentication failures.","severity":"gotcha","affected_versions":"<1.1.0"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Terminate all existing BrowserStack Local processes. If starting multiple local connections, ensure each uses a unique `localIdentifier` in `bs_local_args`. You can also use the `force: true` option in `bs_local_args` to automatically kill other instances.","cause":"An existing BrowserStack Local process is already active on the machine, potentially from a previous test run, a different user, or an older version of the application. Using the same `localIdentifier` for multiple connections can also trigger this.","error":"Another BrowserStack Local Instance Running"},{"fix":"Ensure stable internet connectivity and appropriate firewall/proxy settings. The library (from v1.2.1) attempts to re-download corrupt binaries automatically. If the issue persists, manually delete the binary (typically located in a temporary directory specific to the library) to force a fresh download.","cause":"The downloaded BrowserStack Local binary is damaged or could not be downloaded completely due to network instability, firewall restrictions, or insufficient file permissions.","error":"BrowserStackLocal binary is corrupt"},{"fix":"Verify your internet connection. If you are behind a corporate proxy, ensure that `proxyHost`, `proxyPort`, `proxyUser`, and `proxyPass` are correctly configured in your `bs_local_args`. Check your system's firewall rules to ensure they allow outgoing connections from the BrowserStack Local binary.","cause":"The secure tunnel between your local machine and the BrowserStack cloud could not be established. This often points to network instability, incorrect proxy settings, or firewall blocks preventing outgoing connections from the BrowserStack Local binary.","error":"Local connection not established (or tests failing with 'Host unreachable')"}]}