Quick Start

Build your first Browser Use agent in under 5 minutes

Prerequisites

Before starting, make sure you have:

• Python 3.11 or higher installed
• An API key from a supported LLM provider (we recommend ChatBrowserUse - new signups get $10 free credits)

Browser Use requires Python 3.11+. If you’re on an older version, upgrade first:

python --version  # Check your version

Installation

1. Install uv (recommended)

   The fastest way to get started is with uv, a modern Python package manager:

   curl -LsSf https://astral.sh/uv/install.sh | sh
   

   Or on Windows:

   powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
   

   Already have pip? Skip to the alternative installation method below.

2. Create a new project

   # Create a new directory
   mkdir my-browser-agent
   cd my-browser-agent
   
   # Initialize with uv
   uv init
   
3. Install Browser Use

   # Install the latest version
   uv add browser-use
   uv sync
   

   We ship updates daily - always use the latest version for best results!

4. Install Chromium

   Browser Use needs a Chromium browser to control:

   uvx browser-use install
   

   This downloads and sets up a compatible Chromium browser automatically.

Alternative: Using pip

If you prefer using pip:

pip install browser-use
python -m browser_use install

Set Up Your API Key

1. Get an API key

   Sign up for a free API key from Browser Use Cloud.

   New signups get $10 in free credits to try ChatBrowserUse - the fastest and most accurate model for browser automation.

   You can also use OpenAI, Anthropic, Google, or any other supported provider. See LLM Providers for all options.

2. Create environment file

   Create a .env file in your project directory:

   touch .env
   

   On Windows:

   echo. > .env
   
3. Add your API key

   Open .env and add your key:

   Browser Use

   BROWSER_USE_API_KEY=your-key-here
   

Your First Agent

Create a file called main.py:

main.py

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

load_dotenv()

async def main():
    agent = Agent(
        task="Go to HackerNews and find the top Show HN post",
        llm=ChatBrowserUse(),
    )
    
    result = await agent.run()
    print(result.final_result())

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

Run Your Agent

python main.py

You should see:

• A browser window opening (unless you set headless=True)
• The agent navigating to HackerNews
• Element highlights as the agent analyzes the page
• Console output showing the agent’s actions and reasoning
• The final result printed at the end

First run taking long? The initial run downloads browser binaries and may take a minute. Subsequent runs are much faster!

More Examples

Example 1: Web Search

from browser_use import Agent, ChatBrowserUse
import asyncio

async def main():
    agent = Agent(
        task="Search Google for 'what is browser automation' and tell me the top 3 results",
        llm=ChatBrowserUse(model='bu-2-0'),
    )
    await agent.run()

if __name__ == '__main__':
    asyncio.run(main())

Example 2: Form Filling

from browser_use import Agent, ChatBrowserUse
import asyncio

async def main():
    task = """
    Go to https://httpbin.org/forms/post and fill out the form with:
    - Customer name: John Doe
    - Telephone: [phone]
    - Email: [e-mail]
    - Size: Medium
    - Topping: cheese
    
    Then submit the form and tell me the response.
    """
    
    agent = Agent(task=task, llm=ChatBrowserUse())
    await agent.run()

if __name__ == '__main__':
    asyncio.run(main())

Example 3: Data Extraction

from browser_use import Agent, ChatBrowserUse
import asyncio

async def main():
    task = """
    Go to https://quotes.toscrape.com/ and extract:
    - The first 5 quotes
    - The author of each quote
    - The tags for each quote
    
    Format as: Quote 1: "[text]" - Author: [name] - Tags: [tags]
    """
    
    agent = Agent(task=task, llm=ChatBrowserUse())
    history = await agent.run()
    
    print(history.final_result())

if __name__ == '__main__':
    asyncio.run(main())

Example 4: Structured Output

Get results as typed Python objects:

from browser_use import Agent, ChatOpenAI
from pydantic import BaseModel
import asyncio

class Post(BaseModel):
    post_title: str
    post_url: str
    num_comments: int

class Posts(BaseModel):
    posts: list[Post]

async def main():
    agent = Agent(
        task="Go to HackerNews Show HN and get the first 5 posts",
        llm=ChatOpenAI(model='gpt-4.1-mini'),
        output_model_schema=Posts
    )
    
    history = await agent.run()
    result = history.final_result()
    
    if result:
        parsed = Posts.model_validate_json(result)
        for post in parsed.posts:
            print(f"Title: {post.post_title}")
            print(f"URL: {post.post_url}")
            print(f"Comments: {post.num_comments}")
            print("---")

if __name__ == '__main__':
    asyncio.run(main())

Using Templates (Fast Start)

Browser Use includes ready-to-run templates:

# Generate a basic agent
uvx browser-use init --template default

# Generate with all configuration options
uvx browser-use init --template advanced

# Generate with custom tools examples
uvx browser-use init --template tools

# Custom output file
uvx browser-use init --template default --output my_agent.py

This creates a complete Python file you can run immediately.

Configure the Browser

Customize browser behavior:

from browser_use import Agent, Browser, ChatBrowserUse

browser = Browser(
    headless=False,  # Show browser window
    window_size={'width': 1280, 'height': 720},
    disable_security=False,  # Keep security enabled
)

agent = Agent(
    task="Your task here",
    llm=ChatBrowserUse(),
    browser=browser
)

See the Browser Configuration guide for all available options.

Using Different LLM Providers

ChatBrowserUse (Recommended)

from browser_use import ChatBrowserUse

llm = ChatBrowserUse(model='bu-2-0')  # Optimized for browser automation

Working with Agent History

The run() method returns an AgentHistoryList with useful information:

history = await agent.run()

# Get results
final_result = history.final_result()  # Last extracted content
all_content = history.extracted_content()  # All extracted data

# Analyze execution
history.is_done()  # Check if completed successfully
history.urls()  # All visited URLs
history.action_names()  # All actions performed
history.errors()  # Any errors encountered

# Screenshots and debugging
history.screenshots()  # All screenshots as base64
history.screenshot_paths()  # Paths to saved screenshots

Deploy to Production

The easiest way to run Browser Use in production is with the @sandbox decorator:

from browser_use import Browser, sandbox, ChatBrowserUse
from browser_use.agent.service import Agent
import asyncio

@sandbox()
async def production_task(browser: Browser):
    agent = Agent(
        task="Your production task",
        browser=browser,
        llm=ChatBrowserUse()
    )
    await agent.run()

asyncio.run(production_task())

This handles:

• ✅ Browser provisioning and management
• ✅ Automatic scaling
• ✅ Session persistence
• ✅ Authentication handling

See Going to Production for advanced deployment options including authentication, proxies, and stealth mode.

Troubleshooting

Browser doesn’t open

Make sure Chromium is installed:

uvx browser-use install

Import errors

Ensure you’re using Python 3.11+:

python --version

API key not found

Check that your .env file is in the same directory as your script and properly formatted:

BROWSER_USE_API_KEY=your-key-here  # No quotes, no spaces around =

Slow performance

For faster execution:

1. Use ChatBrowserUse (3-5x faster than other models)
2. Enable flash_mode=True for simple tasks
3. Use Browser Use Cloud with use_cloud=True

agent = Agent(
    task="Fast task",
    llm=ChatBrowserUse(),
    flash_mode=True  # Skip thinking/evaluation for speed
)

Next Steps

Installation Details

Learn about advanced installation options

Browser Configuration

Customize browser behavior and settings

Custom Tools

Extend agents with custom Python functions

Production Deployment

Deploy to production with sandboxes

100+ Examples

Explore real-world use cases

Discord Community

Join 20k+ developers

Need help? Join our Discord community with 20,000+ developers ready to help!