Browser-Use User Guide

Browser-Use is a Python library and CLI tool for AI-powered browser automation. Define tasks in natural language and let an LLM-driven agent autonomously navigate websites, fill forms, extract data, click elements, and perform complex multi-step workflows — all without writing traditional browser automation scripts.

Table of Contents

1. Quick Start
2. Installation
3. Configuration
4. Core Usage
5. Common Tasks
6. CLI Reference
7. Skill CLI (Daemon Mode)
8. MCP Server Mode
9. Cloud Browsers
10. Advanced Features
11. Troubleshooting
12. FAQ

1. Quick Start

Get up and running in under two minutes:

# Install browser-use with CLI support
pip install "browser-use[cli]"

# Install Chromium browser (required for local execution)
browser-use install

# Set your LLM API key
export OPENAI_API_KEY="sk-..."

# Run your first task
browser-use -p "Go to google.com and search for 'Python automation'"

Or use the interactive TUI:

browser-use

Tip

You can skip installation entirely for one-off usage with uvx browser-use which runs in an isolated environment without permanently installing the package.

Minimal Python Script

import asyncio
from browser_use import Agent
from langchain_openai import ChatOpenAI

async def main():
    llm = ChatOpenAI(model="gpt-4o")
    agent = Agent(
        task="Find the top 3 trending repositories on GitHub today",
        llm=llm
    )
    result = await agent.run()
    print(result)

asyncio.run(main())

Using Browser-Use's Own Cloud Model

import asyncio
from browser_use import Agent, ChatBrowserUse

async def main():
    llm = ChatBrowserUse(model="bu-2-0")
    agent = Agent(
        task="Search Google for 'browser automation' and return the top 5 results",
        llm=llm
    )
    result = await agent.run()
    print(result)

asyncio.run(main())

Note

The bu-2-0 model requires a BROWSER_USE_API_KEY. Sign up at browser-use.com to obtain one.

2. Installation

Requirements

Installation Options

Post-Install: Browser Setup

After installing the Python package, you must install a Chromium browser:

browser-use install

This downloads and configures a Chromium binary compatible with browser-use's automation protocol. The browser is stored in your platform's standard cache directory.

Important

On Linux, you may need additional system dependencies for Chromium. Run browser-use install and follow any prompts about missing libraries (typically libnss3, libatk-bridge2.0-0, libdrm2, etc.).

Docker Usage

For containerized environments:

FROM python:3.11-slim

RUN pip install "browser-use[cli]"
RUN browser-use install

ENV IN_DOCKER=true
ENV BROWSER_USE_LOGGING_LEVEL=result

The IN_DOCKER=true environment variable adjusts browser launch flags for container compatibility (adds --no-sandbox, --disable-dev-shm-usage).

Verifying Installation

# Check version
browser-use --version

# Run diagnostics
browser-use doctor

3. Configuration

Environment Variables

Browser-Use is configured primarily through environment variables. Set them in your shell, a .env file, or your CI/CD pipeline.

LLM Provider Keys

Azure OpenAI

Browser-Use Settings

Platform Variables

Configuration File

The Skill CLI supports persistent configuration via config subcommands:

# Set a configuration value
browser-use config set default_model gpt-4o

# Get a configuration value
browser-use config get default_model

# Unset a configuration value
browser-use config unset default_model

Disabling Telemetry

export ANONYMIZED_TELEMETRY=false

Note

Telemetry is anonymized and used to improve the product. No task content, URLs visited, or personal data is transmitted. Only usage patterns (model used, success/failure, timing) are collected.

4. Core Usage

The Agent Class

The Agent is the primary interface for browser automation:

import asyncio
from browser_use import Agent
from langchain_openai import ChatOpenAI

async def main():
    agent = Agent(
        task="Your natural language instruction here",
        llm=ChatOpenAI(model="gpt-4o"),
    )
    result = await agent.run()
    print(result)

asyncio.run(main())

Agent Parameters

Supported LLM Providers

# OpenAI
from langchain_openai import ChatOpenAI
llm = ChatOpenAI(model="gpt-4o")

# Anthropic
from langchain_anthropic import ChatAnthropic
llm = ChatAnthropic(model="claude-sonnet-4-20250514")

# Google Gemini
from langchain_google_genai import ChatGoogleGenerativeAI
llm = ChatGoogleGenerativeAI(model="gemini-2.0-flash")

# Browser-Use Cloud
from browser_use import ChatBrowserUse
llm = ChatBrowserUse(model="bu-2-0")

# DeepSeek
from langchain_openai import ChatOpenAI
llm = ChatOpenAI(model="deepseek-chat", base_url="https://api.deepseek.com/v1")

# Ollama (local)
from langchain_ollama import ChatOllama
llm = ChatOllama(model="llama3")

# Azure OpenAI
from langchain_openai import AzureChatOpenAI
llm = AzureChatOpenAI(
    azure_deployment="your-deployment-name",
    api_version="2024-02-01"
)

Browser Configuration

from browser_use import Agent, Browser, BrowserConfig

config = BrowserConfig(
    headless=False,           # Show the browser window
    window_width=1920,        # Browser width
    window_height=1080,       # Browser height
    user_data_dir="/path/to/profile",  # Persist cookies/sessions
    proxy="http://proxy:8080",         # HTTP proxy
    cdp_url="ws://localhost:9222",     # Connect to existing browser
)

browser = Browser(config=config)
agent = Agent(task="...", llm=llm, browser=browser)
result = await agent.run()
await browser.close()

Custom Actions

Register custom actions the agent can invoke:

from browser_use import Agent, Controller

controller = Controller()

@controller.action("Save data to a file")
def save_to_file(data: str, filename: str):
    with open(filename, "w") as f:
        f.write(data)
    return f"Saved to {filename}"

agent = Agent(
    task="Find the weather in Tokyo and save it to weather.txt",
    llm=llm,
    controller=controller,
)
await agent.run()

Multi-Step Results

result = await agent.run()

# Access the final answer
print(result.final_result())

# Access step history
for step in result.history:
    print(f"Action: {step.action}, Result: {step.result}")

5. Common Tasks

Web Scraping

agent = Agent(
    task="""Go to https://news.ycombinator.com and extract the top 10 stories.
    Return them as a JSON array with fields: title, url, points, comments.""",
    llm=llm,
)
result = await agent.run()

Form Filling

agent = Agent(
    task="""Go to https://example.com/contact and fill out the form:
    - Name: John Doe
    - Email: [email removed]
    - Message: Hello, I'd like to learn more about your services.
    Then submit the form.""",
    llm=llm,
)
await agent.run()

Multi-Page Navigation

agent = Agent(
    task="""
    1. Go to amazon.com
    2. Search for "mechanical keyboard"
    3. Filter by 4+ star rating
    4. Find the cheapest option on the first page
    5. Return the product name, price, and rating
    """,
    llm=llm,
)
result = await agent.run()

File Downloads

from browser_use import Agent, Browser, BrowserConfig

config = BrowserConfig(
    downloads_path="/path/to/downloads"
)
browser = Browser(config=config)

agent = Agent(
    task="Go to https://example.com/reports and download the Q4 2025 PDF report",
    llm=llm,
    browser=browser,
)
await agent.run()

Authentication Workflows

agent = Agent(
    task="""
    Go to https://app.example.com/login
    Log in with username '[email removed]' and password 'secret123'
    After login, navigate to the dashboard and extract the total revenue figure.
    """,
    llm=llm,
)
result = await agent.run()

Warning

Avoid hardcoding credentials in scripts. Use environment variables or a secrets manager. Browser-Use task strings may be logged depending on your logging level.

Data Extraction to File

Browser-Use supports writing results directly to files in multiple formats:

agent = Agent(
    task="""
    Go to https://example.com/pricing and extract all plan details.
    Save the results as a CSV file at ./pricing_data.csv with columns:
    plan_name, monthly_price, annual_price, features
    """,
    llm=llm,
)
await agent.run()

Supported output formats: markdown, txt, json, csv, jsonl, pdf, docx, html, xml.

Screenshots and Recording

from browser_use import Agent, Browser, BrowserConfig

config = BrowserConfig(
    headless=True,
)
browser = Browser(config=config)

agent = Agent(
    task="Go to github.com and take a screenshot of the trending page",
    llm=llm,
    browser=browser,
    save_conversation_path="./conversation_log",
)
result = await agent.run()

# Generate GIF from the session history
# (available when video recording is enabled)

6. CLI Reference

Main CLI

browser-use [OPTIONS]

Options

Examples

# Interactive TUI mode
browser-use

# Single headless task
browser-use -p "Go to example.com and get the page title"

# With specific model
browser-use --model gpt-4o -p "Search for Python tutorials"

# Headless with custom window size
browser-use --headless --window-width 1920 --window-height 1080 -p "Take a screenshot of github.com"

# Connect to existing browser via CDP
browser-use --cdp-url ws://localhost:9222 -p "Navigate to google.com"

# Through a proxy
browser-use --proxy-url http://proxy.example.com:8080 -p "Check my IP address"

Subcommands

browser-use auth

Authenticate with the Browser-Use cloud service:

browser-use auth

This stores your API key for cloud features (remote browsers, bu-2-0 model, skills).

browser-use install

Install the Chromium browser and system dependencies:

browser-use install

browser-use init

Generate template files for browser-use projects:

# List available templates
browser-use init --list

# Generate a specific template
browser-use init --template basic --output ./my-project

# Overwrite existing files
browser-use init --template advanced --force

7. Skill CLI (Daemon Mode)

The Skill CLI provides a daemon-based interface for persistent browser sessions with direct commands. This is useful for scripting, pipelines, and integrations that need low-level browser control without natural language overhead.

Starting a Session

# Open a URL
browser-use open https://example.com

# Open with cloud browser
browser-use cloud open https://example.com

Navigation Commands

Interaction Commands

Data Extraction Commands

Cookie Management

# Get all cookies
browser-use cookies get

# Set a cookie
browser-use cookies set name=value domain=.example.com

# Clear cookies
browser-use cookies clear

# Export cookies to file
browser-use cookies export ./cookies.json

# Import cookies from file
browser-use cookies import ./cookies.json

Wait Commands

# Wait for element to appear
browser-use wait element "#loading-complete"

# Wait for text to appear on page
browser-use wait text "Order confirmed"

Session Management

# List active sessions
browser-use sessions

# Connect to existing browser
browser-use connect ws://localhost:9222

# Use a browser profile
browser-use profile-use "Default"

Utility Commands

# Run diagnostics
browser-use doctor

# Initial setup
browser-use setup

# Create tunnel (for remote access)
browser-use tunnel

# Execute Python code in context
browser-use python "print('hello')"

8. MCP Server Mode

Browser-Use can operate as a Model Context Protocol (MCP) server, allowing AI assistants (like Claude Desktop) to use it as a tool:

browser-use --mcp

This starts an MCP-compatible server that exposes browser automation capabilities as tools that MCP clients can invoke.

Integration with Claude Desktop

Add to your Claude Desktop MCP configuration:

{
  "mcpServers": {
    "browser-use": {
      "command": "browser-use",
      "args": ["--mcp"]
    }
  }
}

Tip

MCP mode is particularly useful for giving AI assistants the ability to browse the web, fill forms, and extract information as part of larger workflows.

9. Cloud Browsers

Browser-Use offers cloud-hosted browser instances for scenarios where local browser execution is impractical (serverless, CI/CD, resource-constrained environments).

Setup

# Authenticate with Browser-Use cloud
browser-use auth

# Or set the API key directly
export BROWSER_USE_API_KEY="your-key-here"

Python Usage

from browser_use import Agent, Browser, BrowserConfig, ChatBrowserUse

config = BrowserConfig(
    cdp_url="wss://cloud.browser-use.com/your-session"
)
browser = Browser(config=config)

agent = Agent(
    task="Navigate to example.com",
    llm=ChatBrowserUse(model="bu-2-0"),
    browser=browser,
)
await agent.run()

Skill CLI Cloud Usage

# Open URL in cloud browser
browser-use cloud open https://example.com

# All skill commands work with cloud sessions
browser-use click "Sign In"
browser-use fill "#username" "myuser"

Caution

Cloud browser sessions have connection timeouts. Long-running tasks may experience WebSocket disconnections. For tasks longer than a few minutes, implement checkpointing or break them into smaller subtasks.

10. Advanced Features

Vision Mode

Enable screenshot-based reasoning for the agent to "see" the page:

agent = Agent(
    task="Find the red button on the page and click it",
    llm=llm,
    use_vision=True,
)

Vision mode sends screenshots to the LLM alongside DOM information, enabling the agent to reason about visual layout, colors, and spatial relationships.

Custom Browser Contexts

Maintain separate sessions with isolated cookies, storage, and state:

from browser_use import Browser, BrowserConfig

browser = Browser(config=BrowserConfig(
    user_data_dir="./profiles/session_a"
))

Parallel Agents

Run multiple agents simultaneously:

import asyncio
from browser_use import Agent

async def run_parallel():
    agents = [
        Agent(task="Check weather in New York", llm=llm),
        Agent(task="Check weather in London", llm=llm),
        Agent(task="Check weather in Tokyo", llm=llm),
    ]
    results = await asyncio.gather(*[a.run() for a in agents])
    return results

Persistent Browser Sessions

Keep the browser open across multiple agent runs:

from browser_use import Agent, Browser, BrowserConfig

browser = Browser(config=BrowserConfig(headless=False))

# First task
agent1 = Agent(task="Log into example.com", llm=llm, browser=browser)
await agent1.run()

# Second task (same session, cookies preserved)
agent2 = Agent(task="Go to settings and change display name", llm=llm, browser=browser)
await agent2.run()

await browser.close()

Demo Mode

Browser-Use includes a demo mode that shows an in-browser log panel displaying the agent's reasoning and actions in real-time:

# Enable via Agent configuration or CLI flags
browser-use --debug -p "Search for Python tutorials"

Video Recording and GIF Generation

Record agent sessions for debugging or documentation:

agent = Agent(
    task="Complete the checkout flow",
    llm=llm,
    save_conversation_path="./session_recording",
)
result = await agent.run()
# GIF generation available from recorded history

Skills System

Fetch and use pre-built skills from the Browser-Use API:

# Skills are fetched from browser-use.com
# Requires BROWSER_USE_API_KEY

Skills provide reusable automation patterns for common tasks (login flows, CAPTCHA handling, etc.).

Sandbox Execution with SSE Streaming

For server-side deployments, browser-use supports sandboxed execution with Server-Sent Events for real-time progress:

# SSE streaming provides real-time updates of agent actions
# Useful for building UIs on top of browser-use

11. Troubleshooting

Error: CDP connection refused or Cannot connect to browser

Cause: The Chromium browser is not running or not accepting CDP connections.

Solution:

1. Run browser-use install to ensure Chromium is properly installed
2. If using --cdp-url, verify the target browser is launched with --remote-debugging-port=9222
3. Check that no firewall blocks the connection

Prevention: Always run browser-use install after a fresh pip install. For remote CDP, ensure the browser process stays alive.

Error: WinError 32 - The process cannot access the file (Windows)

Cause: Attempting to use a browser profile directory (--profile-directory or --user-data-dir) while Chrome is already running with that profile.

Solution:

1. Close all Chrome instances using that profile
2. Or use a different profile directory: --user-data-dir ./browser-use-profile

Prevention: Use a dedicated user data directory for browser-use that is separate from your regular Chrome profile.

Error: ERR_TUNNEL_CONNECTION_FAILED (Cloud browsers)

Cause: The cloud browser session connected successfully but cannot reach the target website. Typically a proxy or network configuration issue on the cloud side.

Solution:

1. Retry the connection — transient cloud networking issues resolve quickly
2. Verify your BROWSER_USE_API_KEY is valid and your account is active
3. Check status.browser-use.com for outages

Prevention: Implement retry logic for cloud sessions. Consider fallback to local browser for critical tasks.

Error: WebSocket connection closed unexpectedly

Cause: CDP WebSocket dropped during a cloud or remote browser session. Common with long-running tasks or unstable network connections.

Solution:

1. Break long tasks into smaller subtasks
2. Increase timeout settings if available
3. For cloud sessions, create a new session and resume

Prevention: Design tasks to complete within 2-3 minutes. For longer workflows, checkpoint progress and use persistent state (cookies export/import).

Error: Coordinate offset on Windows High-DPI displays

Cause: Windows display scaling (e.g., 200%) causes click coordinates to be misaligned. The agent clicks in the wrong location.

Solution:

1. Set explicit window dimensions: --window-width 1920 --window-height 1080
2. Or set Windows display scaling to 100% for the browser-use session
3. Run in headless mode where DPI scaling does not apply: --headless

Prevention: Use --headless for production tasks. For debugging, set explicit dimensions that account for your scaling factor.

Error: No API key found or authentication failures

Cause: Missing or incorrect environment variable for the chosen LLM provider.

Solution:

1. Verify the correct env var is set: echo $OPENAI_API_KEY
2. Ensure no trailing whitespace in the key
3. For .env files, confirm they are in the working directory or BROWSER_USE_HOME

Prevention: Use browser-use doctor to validate your configuration. Add API keys to a .env file in your project root.

Error: Agent stuck in a loop / exceeds max steps

Cause: The agent cannot figure out how to accomplish the task, often due to:

• Ambiguous task description
• Website requiring CAPTCHA or unusual interaction patterns
• Pop-ups or overlays blocking the intended element

Solution:

1. Make task descriptions more specific and step-by-step
2. Increase max_steps if the task legitimately requires many actions
3. Use use_vision=True to help the agent understand visual context
4. Add custom actions for complex interactions

Prevention: Write detailed task prompts. Test with --debug to observe agent reasoning. Break complex flows into sequential agent runs.

Error: Cannot select from dropdown / input text in select box

Cause: Some websites use custom dropdown components (not native <select> elements) that require different interaction patterns.

Solution:

1. Use the click action on the dropdown trigger, then click the option
2. For native selects, the agent typically handles them correctly
3. In Skill CLI: browser-use click ".dropdown-trigger" then browser-use click ".option-value"

Prevention: When possible, provide the agent with CSS selectors or descriptive text for non-standard UI components in your task description.

General Debugging Tips

Tip

Set BROWSER_USE_LOGGING_LEVEL=debug for maximum verbosity. This shows every action the agent considers, DOM state, and LLM responses.

# Debug a failing task
BROWSER_USE_LOGGING_LEVEL=debug browser-use -p "Your task here"

To save the full conversation for post-mortem analysis:

agent = Agent(
    task="...",
    llm=llm,
    save_conversation_path="./debug_session",
)

12. FAQ

Q: Which LLM model works best with browser-use?

GPT-4o and Claude Sonnet provide the best balance of capability and cost for most browser automation tasks. The browser-use native model bu-2-0 is specifically tuned for browser tasks and may outperform general-purpose models on complex navigation. For simple tasks, GPT-4o-mini or Gemini Flash offer good results at lower cost.

Q: Can I use browser-use with a local/self-hosted LLM?

Yes. Use Ollama or any OpenAI-compatible API endpoint. Performance depends heavily on the model's ability to understand HTML structure and follow multi-step instructions. Models with at least 30B parameters generally work; smaller models may struggle with complex pages.

from langchain_ollama import ChatOllama
llm = ChatOllama(model="llama3:70b")

Q: How do I handle websites that require login?

Three approaches:

1. Include login steps in your task description
2. Use a user_data_dir with pre-existing session cookies
3. Export/import cookies via the Skill CLI: browser-use cookies import ./session.json

Q: Does browser-use work in headless mode?

Yes. Use --headless on the CLI or BrowserConfig(headless=True) in Python. Headless mode is recommended for production, CI/CD, and server environments. Note that some websites detect headless browsers — browser-use includes stealth measures but they are not foolproof.

Q: Can I run multiple agents on the same browser?

Yes, but each agent should use its own tab or browser context to avoid conflicts. For fully isolated sessions, create separate Browser instances.

Q: How do I reduce LLM token costs?

• Use smaller/cheaper models for simple tasks (gpt-4o-mini, gemini-flash)
• Reduce max_steps to prevent runaway sessions
• Write precise, specific task descriptions to minimize retries
• Disable use_vision when not needed (screenshots consume many tokens)
• Set BROWSER_USE_CALCULATE_COST=true to monitor costs per session

Q: Can I use browser-use behind a corporate proxy?

Yes. Set proxy via CLI flags or browser config:

browser-use --proxy-url http://proxy.corp.com:8080 --proxy-username user --proxy-password pass -p "task"

Or in Python:

config = BrowserConfig(proxy="http://user:[email removed]:8080")

Q: How do I persist browser state between runs?

Use user_data_dir to maintain cookies, localStorage, and browser history:

config = BrowserConfig(user_data_dir="./my_browser_profile")

Or via CLI: --user-data-dir ./my_browser_profile

Q: What happens when a task fails?

The agent returns a result object with the failure information. It does not retry automatically. You can implement retry logic in your application code, or increase max_steps to give the agent more attempts within a single run.

Q: Is browser-use suitable for production web scraping at scale?

Browser-use is best suited for complex, logic-heavy tasks that require reasoning (filling forms, multi-step navigation, conditional workflows). For high-volume simple scraping (thousands of pages with the same structure), traditional tools like Scrapy or Playwright scripts will be more cost-effective. Browser-use excels when the task requires understanding and adapting to page content.

Q: How do I disable telemetry completely?

export ANONYMIZED_TELEMETRY=false

This prevents all telemetry data from being sent.

Q: Can I use browser-use in a Jupyter notebook?

Yes. Since browser-use is async, use the notebook's built-in event loop:

from browser_use import Agent, ChatBrowserUse

llm = ChatBrowserUse(model="bu-2-0")
agent = Agent(task="Go to example.com", llm=llm)
result = await agent.run()

In Jupyter, await works at the top level without asyncio.run().

Important

Browser-Use is under active development. CLI flags, API surfaces, and default behaviors may change between versions. Pin your dependency version in production: pip install browser-use==X.Y.Z. Check the changelog before upgrading.