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
- Create and activate a virtual environment:
uv venv --python 3.11
source .venv/bin/activate
- 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:
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:
- Check our GitHub Issues
- Join our Discord community for support
We welcome contributions! See our Contribution Guide for guidelines on how to help improve
Browser Use.