Welcome to Browser Use Development!

We’re excited to have you join our community of contributors. This guide will help you set up your local development environment quickly and easily.

Quick Setup

If you’re familiar with Python development, here’s the quick way to get started:

git clone https://github.com/browser-use/browser-use
cd browser-use
uv sync --all-extras --dev
# or pip install -U git+https://github.com/browser-use/browser-use.git@main

echo "BROWSER_USE_LOGGING_LEVEL=debug" >> .env

Helper Scripts

We provide several convenient shell scripts in the bin/ directory to help with common development tasks:

# Complete setup script - installs uv, creates a venv, and installs dependencies
./bin/setup.sh

# Run all pre-commit hooks (formatting, linting, type checking)
./bin/lint.sh

# Run the core test suite that's executed in CI
./bin/test.sh

Prerequisites

Browser Use requires Python 3.11 or higher. We recommend using uv for Python environment management.

Detailed Setup Instructions

Clone the Repository

First, clone the Browser Use repository:

git clone https://github.com/browser-use/browser-use
cd browser-use

Environment Setup

  1. Create and activate a virtual environment:
uv venv --python 3.11
source .venv/bin/activate
  1. Install dependencies:
# Install the package in editable mode with all development dependencies
uv sync --all-extras

# Install the default browser
playwright install chromium --with-deps --no-shell

Configuration

Set up your environment variables:

# Copy the example environment file
cp .env.example .env

Or manually create a .env file with the API key for the models you want to use set:

.env
OPENAI_API_KEY=...
ANTHROPIC_API_KEY=
AZURE_ENDPOINT=
AZURE_OPENAI_API_KEY=
GOOGLE_API_KEY=
DEEPSEEK_API_KEY=
GROK_API_KEY=
NOVITA_API_KEY=
BROWSER_USE_LOGGING_LEVEL=debug  # Helpful for development

You can use any LLM model supported by LangChain. See LangChain Models for available options and their specific API key requirements.

Development

After setup, you can:

  • Try demos in the example library with uv run examples/simple.py
  • Run the linter/formatter with uv run ruff format examples/some/file.py
  • Run tests with uv run pytest
  • Build the package with uv build

Linting

# Run the linter on the whole project (must pass for PR to be allowed to merge)
uv run pre-commit run --all-files
# or use our convenience script
./bin/lint.sh

# Install the linter & formatter pre-commit hooks to run automatically
pre-commit install --install-hooks

# Experimental: run the type checker
uv run type

Tests

# Run all tests that run in CI
./bin/test.sh

# Run specific tests
uv run pytest                                                                         # run everything
uv run pytest tests/test_controller.py                                                # run a specific test file
uv run pytest tests/test_sensitive_data.py tests/test_tab_management.py               # run two test files
uv run pytest tests/test_tab_management.py::TestTabManagement::test_user_changes_tab  # run a single test

Build

uv build
uv pip install dist/*.whl

# push build to PyPI (automatically run by Github Actions CI)
uv publish

Getting Help

If you run into any issues:

  1. Check our GitHub Issues
  2. Join our Discord community for support

We welcome contributions! See our Contribution Guide for guidelines on how to help improve Browser Use.