Installation

Complete installation guide for Browser Use with all options and configurations

System Requirements

Before installing Browser Use, verify your system meets these requirements:

Python Version

Python 3.11 or higher is required

Operating Systems

macOS, Linux, Windows (including WSL)

Memory

Minimum 4GB RAM (8GB+ recommended)

Disk Space

~500MB for Browser Use + Chromium

Check Python Version

python --version
# or
python3 --version

If you’re running Python 3.10 or earlier, you must upgrade to Python 3.11+ before installing Browser Use.

Installation Methods

Method 1: Using uv (Recommended)

uv is a fast, modern Python package manager that simplifies dependency management:

1. Install uv

   macOS/Linux

   curl -LsSf https://astral.sh/uv/install.sh | sh
   
2. Create virtual environment

   uv venv --python 3.11
   

   This creates a .venv directory with an isolated Python environment.

3. Activate the environment

   macOS/Linux

   source .venv/bin/activate
   

   You should see (.venv) in your terminal prompt.

4. Install Browser Use

   uv add browser-use
   uv sync
   

   We ship updates daily! Always use the latest version for best performance and newest features.

5. Install Chromium browser

   uvx browser-use install
   

   This downloads a compatible Chromium browser (separate from your system Chrome/Chromium).

Method 2: Using pip

If you prefer traditional pip:

1. Create virtual environment

   python -m venv .venv
   
2. Activate environment

   macOS/Linux

   source .venv/bin/activate
   
3. Install Browser Use

   pip install browser-use
   
4. Install Chromium

   python -m browser_use install
   

Method 3: Install from Source (Development)

For contributors or those who want the absolute latest code:

# Clone the repository
git clone https://github.com/browser-use/browser-use
cd browser-use

# Install with uv
uv sync --all-extras --dev

# Or with pip
pip install -e ".[all]"

# Install Chromium
uvx browser-use install

The development installation includes testing tools, linting, and all optional dependencies.

Optional Dependencies

Browser Use has several optional feature sets you can install:

CLI Features

# Terminal UI for interactive browser control
uv add "browser-use[cli]"
# or
pip install "browser-use[cli]"

Enables the browser-use CLI tool for fast, persistent browser automation:

browser-use open https://example.com
browser-use click 5
browser-use screenshot page.png

Video Recording

# Enable video recording of agent sessions
uv add "browser-use[video]"
# or
pip install "browser-use[video]"

Allows you to record agent sessions as MP4 videos:

browser = Browser(record_video_dir='./recordings')

Cloud Providers

# AWS integration
uv add "browser-use[aws]"

# Oracle Cloud Infrastructure
uv add "browser-use[oci]"

Code Execution

# Jupyter-like code execution for agents
uv add "browser-use[code]"

Enables the CodeAgent for executing Python code:

from browser_use import CodeAgent

agent = CodeAgent(task="Analyze this data with pandas")

All Features

Install everything at once:

uv add "browser-use[all]"
# or
pip install "browser-use[all]"

Browser Installation

Automatic Installation

The recommended way is to use the built-in installer:

uvx browser-use install
# or
python -m browser_use install

This downloads and configures Chromium automatically.

Using System Chrome/Chromium

You can use your system’s Chrome or Chromium installation:

from browser_use import Browser

browser = Browser(
    executable_path='/path/to/chrome'
)

macOS

executable_path='/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'

Docker Installation

For containerized deployments:

FROM python:3.11-slim

# Install system dependencies
RUN apt-get update && apt-get install -y \
    wget \
    gnupg \
    && rm -rf /var/lib/apt/lists/*

# Install Browser Use
RUN pip install browser-use

# Install Chromium
RUN python -m browser_use install

COPY . /app
WORKDIR /app

CMD ["python", "main.py"]

In Docker, Browser Use automatically detects the containerized environment and disables sandboxing (chromium_sandbox=False).

Environment Configuration

API Keys Setup

Create a .env file in your project directory:

touch .env

Add your API keys based on the LLM provider you’re using:

Browser Use (Recommended)

# Get $10 free credits at https://cloud.browser-use.com/new-api-key
BROWSER_USE_API_KEY=your-key-here

Loading Environment Variables

In your Python code:

from dotenv import load_dotenv
import os

# Load .env file
load_dotenv()

# Access variables
api_key = os.getenv('BROWSER_USE_API_KEY')

Advanced Environment Variables

Optional configuration:

.env

# Disable telemetry (we collect anonymous usage data)
ANONYMIZED_TELEMETRY=false

# Logging level
BROWSER_USE_LOGGING_LEVEL=debug  # debug, info, warning, error

# Custom log files
BROWSER_USE_DEBUG_LOG_FILE=./debug.log
BROWSER_USE_INFO_LOG_FILE=./info.log

# Skip automatic logging setup (for MCP or custom logging)
BROWSER_USE_SETUP_LOGGING=false

Verification

Test your installation:

verify.py

from browser_use import Agent, ChatBrowserUse
import asyncio
from dotenv import load_dotenv

load_dotenv()

async def verify():
    print("Testing Browser Use installation...")
    
    agent = Agent(
        task="Go to example.com and tell me the page title",
        llm=ChatBrowserUse(),
    )
    
    history = await agent.run()
    print("\n✅ Installation verified!")
    print(f"Result: {history.final_result()}")

if __name__ == "__main__":
    asyncio.run(verify())

Run it:

python verify.py

You should see a browser window open, navigate to example.com, and print the page title.

Platform-Specific Notes

macOS

On macOS, Browser Use automatically installs pyobjc to detect screen resolution for optimal browser sizing.

Linux

Install system dependencies for GUI:

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install -y \
    libnss3 \
    libatk-bridge2.0-0 \
    libx11-xcb1 \
    libxcomposite1 \
    libxdamage1 \
    libxrandr2 \
    libgbm1 \
    libasound2

# Fedora/RHEL
sudo dnf install -y \
    nss \
    atk \
    libX11-xcb \
    libXcomposite \
    libXdamage \
    libXrandr \
    libgbm \
    alsa-lib

For headless Linux servers, use headless=True:

browser = Browser(headless=True)

Windows

Windows Defender or antivirus software may flag Chromium downloads. You may need to add an exception for Browser Use.

If you encounter issues:

1. Run terminal as Administrator
2. Disable real-time protection temporarily during installation
3. Add C:\Users\YourName\.browser-use to antivirus exclusions

WSL (Windows Subsystem for Linux)

For WSL, you’ll need an X server:

# Install VcXsrv or Xming on Windows
# Then set DISPLAY environment variable
export DISPLAY=:0

# Or run headless
browser = Browser(headless=True)

Updating Browser Use

We ship updates daily with bug fixes and new features.

With uv:

uv sync

With pip:

pip install --upgrade browser-use

Check your version:

import browser_use
print(browser_use.__version__)

Uninstalling

Remove Browser Use:

# With uv
uv remove browser-use

# With pip
pip uninstall browser-use

Clean up browser data:

# Remove downloaded Chromium and cache
rm -rf ~/.browser-use

# On Windows
rmdir /s %USERPROFILE%\.browser-use

Troubleshooting

Module not found errors

Ensure your virtual environment is activated:

# Should show path to .venv
which python

Chromium fails to launch

Try reinstalling Chromium:

uvx browser-use install --force

Permission denied errors

On Linux/macOS, ensure browser binary is executable:

chmod +x ~/.browser-use/chromium/*/chrome

Import takes too long

Browser Use uses lazy imports. Only imported classes are loaded:

# Fast - only loads Agent
from browser_use import Agent

# Slower - loads all classes
from browser_use import *

SSL/Certificate errors

Never disable security in production. Only use for local testing.

For local development only:

browser = Browser(disable_security=True)  # NOT for production!

Next Steps

Quick Start Guide

Build your first agent in 5 minutes

Browser Configuration

Learn all browser customization options

Supported Models

Explore all compatible LLM providers

Examples

Browse 100+ real-world examples

Having issues? Join our Discord community where 20,000+ developers can help, or check GitHub Issues for known problems.