Guide · Open source

How to use browser-use: install and run an AI browser agent

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

Browser Use is an open-source Python library that connects a language model to a web browser, so an AI agent can click, type and navigate pages to finish a task you describe in plain language. This guide is for Python developers who want to prototype an agent that operates websites. By the end you will install the library, write a small agent script, run it on your own machine, and switch it to a cloud browser.

Browser Usebrowser-use/browser-use · ★ 120k · MIT Install options & downloads

Quick start

1Check prerequisites. Confirm you have Python 3.11 or newer, uv installed, and an OpenAI API key or another supported LLM key.
2Install the library. Run uv add browser-use in your project folder.
3Set your keys. Add OPENAI_API_KEY to a .env file. Add BROWSER_USE_API_KEY only if you use BU2 or a cloud browser.
4Save the agent script. Create agent.py with an Agent, a task and an LLM, as in the README example.
5Run the agent. Run uv run agent.py and read the printed result from the agent history.
6Switch to a cloud browser if needed. Set Browser(use_cloud=True) and a BROWSER_USE_API_KEY to run the same agent without a local Chrome install.

What you need before you start

The Python path in the README requires Python 3.11 or newer, the uv package manager, and an OpenAI API key or a key for another supported LLM provider. The example uses OpenAI by default.

Python 3.11 or newer (the README's project setup example uses Python 3.12)
uv package manager
An OpenAI API key, or another supported LLM key
Optional: a Browser Use API key for the BU2 model or cloud browsers

Install browser-use with uv

Install the library with uv. If you are starting a new project, the README suggests running uv init first with Python 3.12.

uv add browser-use

Add your API key to .env

Store your LLM key in a .env file in your project. The optional Browser Use key is only needed for the BU2 model or for cloud browsers.

# .env
OPENAI_API_KEY=your-key
# BROWSER_USE_API_KEY=your-key  # Optional: BU2 model or cloud browser

Write and run a first agent

Save the following as agent.py. It gives the agent a task, a language model, and runs it. The example task asks the agent to find the number of stars of the browser-use repository and print the result. Run it with uv run agent.py. The agent opens a browser, looks up the repository and prints its answer.

To use BU2 instead, replace the ChatOpenAI line with the commented ChatBrowserUse line; it requires BROWSER_USE_API_KEY.

import asyncio

from browser_use import Agent, Browser, ChatBrowserUse, ChatOpenAI
from dotenv import load_dotenv

load_dotenv()

async def main():
    llm = ChatOpenAI(model='gpt-5.6-luna', reasoning_effort='xhigh')
    # llm = ChatBrowserUse(model='bu-2-0')  # Use BU2 instead; requires BROWSER_USE_API_KEY
    agent = Agent(
        task="Find the number of stars of the browser-use repo",
        llm=llm,
        # browser=Browser(use_cloud=True),  # Use a cloud browser; requires BROWSER_USE_API_KEY
    )
    history = await agent.run()
    print(history.final_result())

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

How do you run the agent on a cloud browser?

If Chrome is not available, such as in Docker, CI or serverless environments, you can use a cloud browser. Set BROWSER_USE_API_KEY, then uncomment the browser line in agent.py. The README says the code is otherwise unchanged. Cloud browsers are billed at $0.02 per browser-hour plus network traffic, according to the README's pricing link, and include stealth, residential proxies, CAPTCHA solving and a live view URL.

agent = Agent(
        task="Find the number of stars of the browser-use repo",
        llm=llm,
        browser=Browser(use_cloud=True),
    )

Other ways to use Browser Use

The README also describes a hosted agent API (Path 1), a CLI (Path 2) that you can drive from an AI coding agent, and a Claude toolset integration in which Browser Use implements 31 browser actions. This guide covers only the Python library path.

Hosted agent API: start from the API quickstart in the docs
CLI: the README gives a prompt to paste into an agent such as Claude Code
Claude toolsets: Browser Use drives a local, cloud or CDP-connected browser

What people use it for

Looking up a fact on a website, such as the number of stars on a GitHub repository, as in the README example
Automating repetitive multi-step web tasks like lookups or form filling
Booking-style tasks that need clicking, picking dates and handling a CAPTCHA, as shown in the README demo
Running browser agents in Docker, CI or serverless environments via a cloud browser

Frequently asked questions

Is browser-use free?

The browser-use library is released under the MIT licence, which the README lists. You still pay your LLM provider for model calls, and cloud browsers are billed at $0.02 per browser-hour plus network traffic according to the README.

What do I need to install browser-use?

The README lists Python 3.11 or newer, the uv package manager and an OpenAI API key or another supported LLM key. Install the library with uv add browser-use.

Does browser-use need Chrome installed?

The local path runs a browser on your machine. The README says a cloud browser needs no Chrome install and works in Docker, CI and serverless setups, so use Browser(use_cloud=True) in those environments.

Can I use browser-use without an OpenAI key?

The README says you can use another supported LLM key instead of OpenAI. The BU2 model through ChatBrowserUse requires a BROWSER_USE_API_KEY.

How does browser-use compare to Playwright?

Playwright is a browser automation library where you write deterministic scripts. Browser Use puts a language model in the loop so the agent decides the next click from your plain-language task, which makes its behaviour less predictable.

Why did my agent give a different result when I ran it again?

The README notes that the agent's behaviour depends on a language model, so it is not fully deterministic. Use a fixed task, check the printed history, and use a dedicated script if you need repeatable steps.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Browser Use suits Python developers who want to prototype an AI agent that operates websites, especially if they want to run it locally with their own LLM key or need a cloud browser for Docker or CI. It is a poor fit for non-programmers wanting a no-code tool, or for projects that need fully deterministic scripts, where Playwright or a similar tool is the better choice.

Install options & downloads