Early-bird pricing (ends Dec 25), locked in while you stay subscribed: Go $10/mo (normally $20), Plus with Opus 5.5 just $30/mo (normally $50)Subscribe →

Browser-Use 1.0: Setup and Migration Guide

If you built on browser-use 0.x, version 1.0 changes the architecture and the defaults. One persistent Python REPL replaces 24 browser actions, and Browser() now means a cloud browser. This guide covers pinning 1.0.7, first run, and 0.x migration using the 1.0.7 release notes, MIGRATING.md, and the November 20 engineering post.

Get 1.0 running in 5 minutes

Pin the release. Version 1.0.0 landed November 10, 2026 and 1.0.7 was the stable tag by November 20, with 1.0.8rc1 in pre-release (releases). The README explicitly tells you never to use >= because APIs break between minors.

bash
uv add 'browser-use==1.0.7'
# or
pip install 'browser-use==1.0.7'

Requirements are narrow: Python 3.11 or newer and below 4.0 (README, PyPI). Every dependency is pinned with ==, which helps reproducibility but can conflict when your app also needs a different pydantic, mcp, or google-genai version.

Authenticate once. Create a key at cloud.browser-use.com, then either export it or run the login helper:

bash
export BROWSER_USE_API_KEY=bu_...
# or
browser-use login

Login stores credentials in ~/.config/browser-harness/auth.json and is shared by the CLI, MCP server, and browser-harness (MIGRATING.md). In containers use BROWSER_USE_AUTO_LOGIN=true; on SSH or headless machines the 1.0.8 release candidate prints a link plus approval code you approve from another device (1.0.8rc1 notes).

Your first run is three lines:

python
from browser_use import Agent

result = Agent(
    "Find the number of stars of the browser-use repo"
).run_sync()

print(result.final_result())

That is a billable run by default: it uses a Browser Use Cloud browser and the default gateway model (README Path 1 / Path 3, MIGRATING.md defaults). If you want zero cloud spend for this test, add Browser('chromium') and your own llm now.

What replaced your 24 actions

Browser-use 0.x gave the model a menu: pick one action per step from a DOM dump. Version 1.0 deletes that menu. The model gets one main python tool — a persistent REPL with browser-harness helpers and raw cdp() pre-imported — built on Pydantic AI (engineering post):

python
async def python(ctx: RunContext[Session], code: str) -> list[Any]:
    """Run Python in the persistent REPL
    (browser-harness helpers and raw cdp() pre-imported)."""

The deletion cut 136,905 lines and added 29,601 across 554 files, Python files from 178 to 43 (engineering post).

The clearest demo is a hung-page recovery: the agent called Page.stopLoading, blocked the stuck script, reloaded, found the page's private JSONP endpoint, then fetched 730 dates in batches and retried only failed batches — returning 4,720 rows with no dedicated tool for any of that (engineering post).

The rule the team kept: build a helper only when the model cannot rewrite it after reading it once. The exception is CAPTCHA. Prose instructions scored 0/3 on hCaptcha in a small staging test while the dedicated solve_captcha tool went 6/6, because the tool flips a solver switch the page cannot reach (engineering post).

On cost and speed, read the footnote before the headline. The November 20 post reports the same three models scoring 14–33 points higher at 2.7–5.2x lower cost on 1.0 versus 0.x, on a 200-task run from November 8 with 180 tasks scored. It explicitly warns the test was one run per model with changed defaults, so the tool redesign cannot take all the credit (engineering post).

The cleaner comparisons are narrower. Version 1.0.4 scored 76.1 versus 76.0 on 1.0.3 while model cost fell from $0.434 to $0.208 per task after batch screenshot pruning preserved prompt caching (1.0.4 notes). BU Bench v2 put 1.0 ultrafast at 62.5, $0.070, and 650 seconds against Browser Use Pi at 56.3, $0.082, and 743 seconds, a gap the authors say loses significance once provider errors are excluded. Budget for cheaper and faster, not automatically smarter.

Defaults that silently change your bill and browser

Table compiled from MIGRATING.md and the 1.0.6 release notes; it reflects 1.0.7 and the mid-1.0 default-model switch older guides miss.

Setting0.x1.0.7
llm=NoneRequired a modelbu-4.0 via Browser Use gateway
bu-4.0 pricen/a$1.80 / 1M input, $9.00 / 1M output
bu-fast pricen/a$0.12 / 1M input, $0.60 / 1M output
Browser()Local ChromiumBrowser Use Cloud browser
Local browserDefaultBrowser('chromium') explicitly
API keyOne per providerOne BROWSER_USE_API_KEY
max_steps500100 (one step reserved for delivery)
Agent timeoutUnspecified1,700 seconds, excluding startup/shutdown
JudgeOpt-injudge=True by default
Reasoning / moden/areasoning='medium', mode='ultrafast' on bu-fast / bu-ultrafast
Gateway model price per 1M tokens, bu-4.0 versus bu-fast

Three traps deserve emphasis. First, the default model changed mid-1.0: releases through 1.0.5 defaulted to bu-fast, but 1.0.6 switched the default to bu-4.0 at 15x the token price — the project's own example puts the same short test at $0.022 on bu-4.0 versus $0.0014 on bu-fast. Pass llm='bu-fast' explicitly if you want the old cost profile. Second, a bare Browser() now provisions a cloud browser at $0.06 per browser-hour plus model and per-search charges (README), and cloud browsers cannot reach localhost or private IPs (MIGRATING.md). Third, one step equals one model request and one Python cell, so the lower 100-step cap also acts as a spend limit; max_steps < 1 or timeout <= 0 now fails before the browser starts (MIGRATING.md).

The judge is the other hidden line item. After any run with at least one step, your own model makes one extra low-effort request over up to 120,000 characters of trace plus, with vision on, the last four distinct images including the final page, sent unredacted (MIGRATING.md). Results land in result.judgement with success, failure_reason, gotchas, and bot/captcha flags, and the cost counts toward result.cost_usd. Disable it with judge=False or pass judge_context with the expected answer, and set use_vision=False if screenshots must never leave your boundary.

Stay local when you must

Choose the browser for the network, not for habit. The model identifier below is the illustrative provider example from the README's local-browser snippet (README):

python
from browser_use import Agent, Browser, ChatOpenAI

agent = Agent(
    "Summarize the dashboard at http://localhost:3000",
    llm=ChatOpenAI("gpt-6-luna"),
    browser=Browser("chromium"),
)
print(agent.run_sync().final_result())

Use Browser('chromium') for localhost, private networks, custom viewports, or any case where cloud device-metrics calls will not change the actual page viewport. Use Browser('chrome') to drive your already-open Chrome with existing logins; Browser('chrome', profile='Work') launches a temporary copy with logins but no Sync writes back, and on Windows quit the original Chrome first because it locks cookies (MIGRATING.md). Cloud stays the right default when you need managed stealth, proxies, CAPTCHA handling, or zero local setup (README) — just budget browser-hours separately from tokens.

Custom models still work, but the path matters (MIGRATING.md):

  • Gateway aliases: bu-4.0, bu-4.0-mini, bu-4.0-pro, bu-fast, bu-ultrafast, bu-smart
  • Providers: ChatOpenAI, ChatAnthropic, ChatGoogle, or Pydantic AI strings such as groq:llama-3.3-70b-versatile
  • Azure via llm='azure:<deployment>' with AZURE_OPENAI_ENDPOINT, AZURE_OPENAI_API_KEY, and OPENAI_API_VERSION

LangChain chat objects as Agent(llm=...) now raise TypeError, and retired gateway names like bu-2-0 are rejected before a browser starts. Each parallel agent needs its own Browser(); two agents sharing one raises RuntimeError, though one keep_alive=True browser can be reused sequentially (MIGRATING.md).

Migrate without guessing: let the error tell you

Version 1.0 fails fast on purpose. Removed imports raise ImportError naming the replacement, unsupported Agent(...) arguments raise TypeError, and anything 1.0 cannot honor errors before a browser starts or anything is billed (MIGRATING.md). A smaller set — use_vision=True, vision_detail_level, max_actions_per_step, flash_mode, max_failures, highlight_elements, and similar tuning flags — is accepted but ignored with one warning each; use_vision=False remains meaningful because it stops screenshots from reaching the model.

After startup the behavior flips: run() generally returns an error result instead of raising, with status='error' and details in result.error. Only cancellation still propagates. Update your checks accordingly:

python
# 0.x
history = await agent.run(max_steps=500)
ok = history.is_successful()

# 1.0
result = await agent.run(max_steps=100)
ok = result.is_done() and result.success is not False

is_done() now means only that the run completed; success lives in the model's finish(result, success) verdict, and is_successful() returns None when the model gave no verdict. The old per-step history helpers (action_names(), model_actions(), extracted_content(), save_as_playwright_script(), and the rest listed under removed history APIs in MIGRATING.md) are gone; read result.messages, result.status, result.partial, files in agent.workspace, and result.judgement instead.

Start with these three edits: move max_steps from Agent(...) to agent.run(max_steps=...), replace removed callbacks (on_step_start, pause, stop, multi_act, save_history) with logging.getLogger('browser_use') at INFO or BROWSER_USE_LOGGING_LEVEL=warning, and re-scope secrets. Domain-scoped secrets now type only on matching pages, names ending in bu_2fa_code are treated as TOTP seeds, the old <secret>name</secret> placeholder raises and must become type_secret('name'), and values are redacted as <secret:name> in cells and results — which is redaction, not a sandbox, since model-written Python can still read them (MIGRATING.md). If you need time, pin pip install 'browser-use<1' and migrate on a branch.

"browser use is more a python framework for building your own browsing agent" — u/Starks1293 on r/ClaudeCode

That framing matches how users describe it in Reddit discussions: a framework for building browsing agents, often mentioned for bot-guarded sites and code-level control. Reliability remains model- and site-dependent; one production report describes five minutes and nine failed steps on basic form filling.

Before production: judge, secrets, and hit-or-miss reality

For power use, what matters:

  • Typed results via output_model_schema, read from result.structured_output
  • Workspace uploads and workspace/downloads with result.downloads
  • Domain controls (allowed_domains, prohibited_domains, block_ip_addresses), which guard an aligned model rather than sandboxing the network
  • Opt-in web_search=True, billed per search into result.cost_usd
  • CLI/MCP via browser-use --cli-mcp, browser-use skill install, and browser-use --doctor

Treat 1.0 like a fast-moving framework: pin exact versions, add judge_context on long tasks, checkpoint partial work with checkpoint('titles.json', titles, partial=True), and run untrusted tasks in containers because domain limits and secret redaction are not isolation (README).

Migrate now, pin, or stay on 0.x?

SituationDo this
New agent project, cloud OKStart on ==1.0.7, keep bu-4.0 default, keep judge on
Cost-sensitive batch jobsPass llm='bu-fast' and judge=False, measure before scaling
Localhost / intranet / custom viewportBrowser('chromium') plus your own model, never bare Browser()
Existing 0.x in productionPin browser-use<1 on main, migrate on a branch using the fail-fast errors
CAPTCHA-heavy flowBudget for the dedicated solver; prose instructions alone went 0/3 in the team's test

You gain an agent that can block a hung script or call a private API you never wrapped, but you lose the guardrails of a fixed action menu. If that trade works for your site, migrate; if not, staying pinned with browser-use<1 while you evaluate remains the safer option for existing production systems.

FAQ

What is new in browser-use 1.0?

One persistent Python REPL with browser-harness helpers and raw CDP replaces the 24-action menu from 0.x, removing roughly 80% of the library (Python files from 178 to 43). Defaults switch to Browser Use Cloud, a gateway model, and a single BROWSER_USE_API_KEY.

Will my 0.x code break?

Common entry points (Agent, Browser, run(), final_result()) still exist, but removed imports and options raise ImportError or TypeError before billing, max_steps moved to run(), and Browser() now means cloud. Pin browser-use<1 to stay, or migrate branch-first.

Can I still use my own model and a local browser?

Yes. Pass providers like ChatOpenAI, ChatAnthropic, ChatGoogle, or a Pydantic AI string, and use Browser('chromium') for a fresh local browser or Browser('chrome') for your open Chrome. Cloud browsers cannot reach localhost.

Which Python version does browser-use 1.0 need?

Python 3.11 or newer and below 4.0. Exact dependency pins can conflict with other packages, so install in a fresh virtual environment first.

How do I disable the run judge?

Pass judge=False to skip the extra judging request, or judge_context with your acceptance criteria to make its verdict useful. Set use_vision=False if judge screenshots must not be sent.