Carview!

@tomlin7

What's Changed

fix: use user-provided executable_path instead of defaulting to chromium by @tomlin7 in #2373
fix: ensure new browser context is created for video recording in existing sessions by @better-salmon in #2398
More robust file syste by @mertunsall in #2402
Revamp API docs by @sauravpanda in #2409
add deepseek llm chat model by @BoneCARD in #2397
added new getting_started examples by @sauravpanda in #2413
FLASH MODE by @mertunsall in #2427
Remove Planner Prompt and Small Fix to lmnr by @mertunsall in #2434
Add OpenAI CUA fallback by @mertunsall in #2359
laminar-ignore input output by @MagMueller in #2386
lmnr ignore input for _is_page_responsive by @MagMueller in #2438
Limit wait action to 10 seconds by @mertunsall in #2437
lmnr ignore input by @MagMueller in #2440
Fix incorrect pip install prompt for CLI addon by @fureigh in #2442
Update screenshot handling for empty pages in BrowserSession by @mertunsall in #2448
Fix: Only configure MCP server logging when server is instantiated, n… by @pirate in #2456
support tool calling with groq by @mertunsall in #2459
New release by @mertunsall in #2463

New Contributors

@tomlin7 made their first contribution in #2373
@better-salmon made their first contribution in #2398
@BoneCARD made their first contribution in #2397
@fureigh made their first contribution in #2442

Full Changelog: 0.5.4...0.5.5

@MagMueller

🏥 Agent Now Auto-Recovers Crashed Pages

The agent can now handle automatic recovery in these scenarios:

💅 If Page has render-blocking network requests that never complete (e.g. stalled CSS/JS requests in <head>)
😵‍💫 If Page tries to run while (true) {} or other CPU-hogging JS code that crashes page's JS runtime
📜 If Page over >50,000px eats all VRAM during screenshot or too many large images/videos eat all CPU or RAM
👋 If Page, BrowserContext, or Browser is closed by a human or other tool while being used by the Agent
🎭 If Browser, BrowserContext, or CDP gets closed / disconnects / becomes unresponsive due to sytem load or crashes
👤 If Browser fails to launch because user_data_dir is missing / corrupt / SingletonLocked by another Chrome

Previously, you may have seen some of these cryptic errors when pages crashed:

❌ TargetClosedError: Target page, context or browser has been closed
⚠️ Timeout 30000ms exceeded. Call log: - taking page screenshot
🔓 Failed to take screenshot: FileNotFoundError: [Errno 2] No such file or directory: '/tmp/browser_use_semaphores/screenshot_global.00.lock'
👤 Chromium launch error: Failed for unknown reason with user_data_dir= ~/.config/browseruse/default

But now, the agent properly handles most common crashes by taking the following steps:

😤 attempts to use stalled page anyway as long as JS page.evaluate(1)works (sometimes ok even if load never finishes)
♻️ if that fails, attempt to close and re-open the same URL in a new tab to avoid transient loading issues or specific crashed tab
🤷‍♂️ if that fails, close the crashing URL and retreat back to about:blank so the LLM can keep trying different approaches instead of crashing the whole Agent task
🤯 if the connected browser ever crashes, Agent automatically kills it and re-opens a new browser with the same settings
👤 if the browser ever fails to (re)launch, e.g. due to bad user_data_dir, BrowserSession will fall back to using a tmp incognito user_data_dir=None and any provided storage_state.json cookies.

Please open an issue if you encounter any problems or deviations from this expected behavior!

Tip

🐢 You can increase the default navigation and page interaction timeouts when dealing with slow network or servers:

📈 Re-use our new native retry decorators in your own projects & custom actions for more stable & consistent behavior:

bubus/helpers.py: @retry(timeout=5, wait=1, retries=2, ...)
browser_use/browser/session.py: @require_healthy_browser(usable_page=True, reopen_page=True)

💔 Upcoming Changes: What comes after Playwright-python?

We're gradually transitioning from Playwright to our own in-house library browser-use/cdp-use to unlock additional browser APIs and deliver better performance & stability for the Browser-Use Agent.

Why the Switch?

Playwright has architectural limitations that clash with our use case. Built primarily for cross-browser consistency and QA testing, it relies on a singleton Node.js WebSocket relay subprocess that frequently conflicts with long-running Python asyncio server-side backends. It sometimes makes blocking sync calls from async code during RPC operations, rendering timeouts unenforceable at the browser-use level and leading to random Agent crashes and deadlocks under high load.

This forces us into defensive programming hell: external forked watchdog monitors that kill parent processes when they stall, leading to flakiness on slower machines, which demands 1-per-machine global semaphores, plus the delightful ritual of kill -9 -killasgroup to eliminate zombie browser processes. It's a complexity snowball stemming from a leaky abstraction chain of async Python → Node.js → CDP → browser, we're hoping to improve it by eliminating one layer (the Node.js playwright relay).

The Breaking Point

We've burned too much time building and maintaining buggy workaround wrappers to sidestep Playwright issues. Recently, we experimented with dropping Playwright calls entirely in favor of direct CDP commands—and the speed and stability improvements were immediately encouraging.

We're also keeping a close eye on the upcoming [WebDriver BiDi spec](https://www.w3.org/TR/webdriver-bidi/) that may eventually replace CDP, while learning from other browser driver layers in the ecosystem: BrowserQL, Puppeteer, Stagehand, mcp-b.ai, Selenium, Cypress, TamperMonkey, and friends.

What This Means for You

Don't panic. We're maintaining existing Playwright API compatibility and interop between browser-use methods and Playwright objects for the 0.5.x series. As a library or application user, you shouldn't notice any changes—provided you're using a Chromium-based browser (Brave, Ungoogled Chromium, Edge, Opera, etc.) via CDP.

Firefox and Safari support? Not in the main library right now. We're focused on mastering CDP stealth first, though we may circle back to support them eventually. In the meantime, we encourage community contributions of alternative BrowserSession() implementations that users can pass to Agent() (🕶️ think NinjaBrowserSession() for extra stealth, WebdriverBidiBrowserSession(), ExtensionBridgeBrowserSession(), etc.).

📣 Ready to help build the future? Join us at cdp-use + #2400!

What's Changed

fix-lmnr-serilization by @MagMueller in #2369
eval fix cookie judge by @MagMueller in #2372
Fix auto download and available file paths by @mertunsall in #2377
pdf file creation supported. by @mertunsall in #2375
change laminar debug secret by @MagMueller in #2378
Ignore about:blank tab in context by @mertunsall in #2374
eval laminar key name by @MagMueller in #2382
eval remove laminar args by @MagMueller in #2384
always tell agent to not use credentials unless necessary when provid… by @Alezander9 in #2388
add 2FA usage into the auth prompt injeection section by @Alezander9 in #2389
Openrouter evals support by @gregpr07 in #2391
updated gmail example with oauth setup guide by @sauravpanda in #2393
combine redundant BrowserSession helper methods: navigate(), navigate_to(), create_new_tab(), new_page(), etc. into just navigate(url: str, new_tab: bool, timeout_ms: int) by @pirate

Full Changelog: 0.5.3...0.5.4

@pirate

🕶️ Browser now falls back to incognito when given unusable `user_data_dir`

👤 BrowserSession(user_data_dir='/path/to/some/profile') will now fall back to using a temporary incognito 🕶️ user_data_dir=None profile in any cases where the browser fails to launch with the one your provide (instead of just crashing).

user_data_dirs becoming unusable can happen quite frequently due to:

🧩 user_data_dir got corrupted (due to chrome being killed mid-launch too many times, files deleted by accident, or if it got migrated to a newer backwards-incompatible version by a chrome update)
🔒 user_data_dir/SingletonLock conflict due to multiple chrome instances trying to share a single profile dir
🗄️ user_data_dir filesystem permissions, missing network mount, FSYNC support, or preferences registry issue

Important

If any of these user_data_dir edge cases are encountered, you may notice the Agent will now proceed anyway with a blank profile and no logins/cookies.

This is intentional as we want to push people towards using a storage_state.json and sensitive_data instead of user_data_dirs for managing logins and auth credentials. user_data_dir are heavy (often >1Gb), easily corrupted, and not cross-compatible between browser versions/OSs/CPU architectures, in contrast storage_state JSON files are lightweight, updated atomically to avoid corruption, and are safe to share across many browsers in highly parallel environments.

What's Changed

get fresh page on every screenshot, fix dvd animation logo image by @pirate in #2354
Automatically Download PDFs when reached, scroll with Pure CDP to scroll inside PDF by @mertunsall in #2349
get base64 cdp screenshots directly without playwright by @pirate in #2362
feat: forward unikraft data to the eval workflow .yaml by @reformedot in #2356
hot-fix-Increase-timeouts & fix remove message by @MagMueller in #2358
refactor-agent-stable by @MagMueller in #2355
more error categories by @Alezander9 in #2366

Full Changelog: 0.5.2...0.5.3

@MagMueller

What's Changed

hot-fix-screenshot by @MagMueller in #2351
Restore global multiprocess lock during screenshots, limit 1 at a time per machine actually makes them all go faster #2352
Always use manual subprocess spawn + CDP to connect to local browser instead of playwright launch() by @pirate in #2347
cursor/implement-scroll-functionality-with-index-e993 by @MagMueller in #2348

Full Changelog: 0.5.0...0.5.2

@pirate

Ⓜ️©🅟 Native Bidirectional MCP Support

➡️ Expose external MCP servers & tools to the Browser Use agent, and
⬅️ Expose Browser Use's core tools & the full Agent as an MCP server callable by other MCP clients

MCP in both directions is now supported natively 🎉

Screenshot 2025-07-07 at 9 53 40 PM Browser-Use AI Browser Automation

Example: Use it with Claude Desktop

Option A: Download the browser-use.dxt Claude Desktop Extension below, and double-clickt to use it (recommended)
Option B: Install the MCP server manually in your Claude Desktop config .json

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

What's Changed

Add MCP Client & Server Support by @pirate in #2297
Allow connecting multiple MCP servers to browser-use Agent and expose their tools as actions by @pirate in #2344
MCP server logging stderr redirection by @pirate in #2346
Improvements to ~/.config/browseruse/config.json schema for use with new MCP client and server connectors
feat: add parameters to remove images and css in the eval.yaml by @reformedot in #2337
better error handling and lmnr inclusion by @MagMueller in #2333
Enhances scroll functionality with pixel control by @DanielTea in #2338

Full Changelog: 0.4.5...0.5.0

@MagMueller

What's Changed

eval enable debug by @MagMueller in #2284
Update eval.yaml by @sauravpanda in #2285
Update eval.yaml by @sauravpanda in #2286
eval: passing 2fa tokens without json parsing by @sauravpanda in #2289
OpenRouter Support by @willbonde in #2277
Add judge evaluation to login tasks by @mertunsall in #2288
feat: added gmail api integration to get OTPs and email by @sauravpanda in #2259
feat: add support for anchor browser when running evals by @BroskyBrowser in #1878
feat: multiple browser support for the eval script by @reformedot in #2295
make eval service fetch rotating auth info from server by @Alezander9 in #2263
Add basic support for JSON, CSV, and reading PDFs. by @mertunsall in #2296
feat by @mertunsall in #2291
fixing detection of interactive elements in Shadow DOM by @limingzhong61 in #2294
feat: added support for Browserbase and Hyperbrowser as available browsers in the eval by @reformedot in #2301
fix: handle eval import errors by @reformedot in #2302
fix-screenshot-test by @Alezander9 in #2305
fix docs icon by @os1rix in #2298
fix: improve browserbase eval params by @reformedot in #2303
Refactor eval into smaller files (for real this time) by @Alezander9 in #2306
eval-repeat-judge by @MagMueller in #2308
parallel judges by @MagMueller in #2309
fix reasoning text display by @MagMueller in #2310
add max diff btw judges by @MagMueller in #2311
add multiple last screenshots to llm input message by @MagMueller in #2313
multiple images per step with label by @MagMueller in #2315
eval-log-level by @MagMueller in #2316
Add Qwen2.5 VL to eval and fix order of example by @mertunsall in #2317
feat: added browser settings to browser profile by @reformedot in #2318
eval-update-judge-file-system-error by @MagMueller in #2319
update extract_structured_data description by @MagMueller in #2320
system prompt for open ended and specifc tasks by @MagMueller in #2321
reaoning rules for user request by @MagMueller in #2322
Update judge summary by @MagMueller in #2323
system prompt alternative ways by @MagMueller in #2325
system prompt typos by @MagMueller in #2326
Fix: don’t drop real title fields when optimising schema by @ai-christianson in #2324
fix: update eval.yaml to use full HD screen resolution by @reformedot in #2329
Make tool call example parameter optional by @mertunsall in #2327
Revert "Make tool call example parameter optional" by @mertunsall in #2331
Move tests and put examples into system prompt instead by @mertunsall in #2332
New Release 0.4.5 by @mertunsall in #2334

New Contributors

@willbonde made their first contribution in #2277
@reformedot made their first contribution in #2295
@ai-christianson made their first contribution in #2324

Full Changelog: 0.4.4...0.4.5

@MagMueller

What's Changed

.github/workflows: Migrate workflows to Blacksmith runners by @blacksmith-sh in #2195
eval-back-to-github-actions by @MagMueller in #2196
agent-add-step-info-to-take-step by @MagMueller in #2197
eval-judge-error-categories by @MagMueller in #2202
Improve system prompts by @mertunsall in #2209
Improve judge system by @mertunsall in #2210
eval-add-anchor-arg by @MagMueller in #2211
eval-add-anchor-arg2 by @MagMueller in #2212
Add Cloudflare challenge as captcha error by @mertunsall in #2216
Fix name not defined error in example in agent-settings.mdx by @philippwiederkehr in #2203
eval-runner-more-ram by @MagMueller in #2217
eval-runner-16-core by @MagMueller in #2219
eval-runner-remove-space by @MagMueller in #2220
Fix screenshot clip errors at end of scroll height by @pirate in #2214
eval-runner-name by @MagMueller in #2221
eval-runner-group by @MagMueller in #2222
eval-test-new-runners by @MagMueller in #2225
dont use fs for short tasks, dont initialize results.md by @mertunsall in #2218
eval-4-core-runners by @MagMueller in #2227
feat: resilient memory by @mertunsall in #2223
Update model names for gemini-2.5 to remove preview suffixes in servi… by @mertunsall in #2228
Add reasoning_low parameter to OpenAI chat model by @mertunsall in #2236
Remove xpath from input text action by @mertunsall in #2239
fix by @mertunsall in #2241
Remove xpath from click_element_by_index by @mertunsall in #2240
Add sensitive data example by @mertunsall in #2243
remove git function helpers by @MagMueller in #2244
Quick fix for eval by @mertunsall in #2246
Remove mem0 dependencies from pyproject by @mertunsall in #2245
Clarify new elements tagging criteria by @mertunsall in #2249
New element updates in browser state by @mertunsall in #2248
eval include runner link by @MagMueller in #2253
add haiku to evals by @mertunsall in #2257
eval-runner-status-updates by @MagMueller in #2256
Refactoring dom process tree script by @gregpr07 in #2258
Fix browser use library output by @gregpr07 in #2260
fix: groq model config by @mertunsall in #2261
eval-change-timing by @MagMueller in #2262
Update eval.yaml by @sauravpanda in #2270
eval-dont-go-to-the-website by @MagMueller in #2271
LLM Updates by @mertunsall in #2273
fix: openai pricing by @mertunsall in #2278
Update model pricing by @LarsenCundric in #2280
fix for new release by @mertunsall in #2282

New Contributors

@blacksmith-sh made their first contribution in #2195
@philippwiederkehr made their first contribution in #2203

Full Changelog: 0.4.2...0.4.3

@mertunsall

What's Changed

no screenshot in the beginning blank page by @mertunsall in #2154
Fix dollar symbol escaping in model recommendations for Mintlify compatibility by @Spinny03 in #2153
Add support for more models by @gregpr07 in #2143
Structured output optimizations by @gregpr07 in #2157
Implement structured output for judge system by @MagMueller in #2160
Fix schema definition by @MagMueller in #2161
Fix structured output schema conversion and improve error handling by @MagMueller in #2163
eval-judge-improvements by @MagMueller in #2168
judge-new-output-format by @MagMueller in #2169
fix-judge-format by @MagMueller in #2170
Make login tasks in eval be evaluated by presence of login cookie instead of webjudge by @Alezander9 in #2012
Fix judge system for structured output compatibility by @MagMueller in #2172
Nicer structured output by @gregpr07 in #2173
fix-screenshot-changes-screen-size by @MagMueller in #2174
added usage data to agent history and evals by @gregpr07 in #2171
log-token-usage by @MagMueller in #2176
log-token-usage-specific by @MagMueller in #2177
feature/thinking-parameter by @MagMueller in #2178
fix-usage-count-to-json by @MagMueller in #2183
Fix eval by @mertunsall in #2184
Add upload file action by @mertunsall in #2185
Remove save_pdf action by @mertunsall in #2186
Clean Controller by @mertunsall in #2187
eval-runners-use-blacksmith by @MagMueller in #2190
eval-remove-env-from-runner by @MagMueller in #2191
eval-runners-logging by @MagMueller in #2192
eval-runners-disable-cache by @MagMueller in #2193
eval-runners-cache-enable by @MagMueller in #2194

New Contributors

@Spinny03 made their first contribution in #2153

Full Changelog: 0.4.1...0.4.2

@MagMueller

Important ⚠️

BETA release while we continue migrating off langchain and implementing more models + features, wait for 0.4.5 ish for next stable release.

What's Changed

Improve judge system evaluation criteria by @MagMueller in #2121
Remove unused controller telemetry functionality by @MagMueller in #2123
Add explicit scoring criteria for tasks with no output by @MagMueller in #2124
use retry decorator for locking and timeouts instead of manual logic by @pirate in #2126
Set-default-parameter by @MagMueller in #2128
Use a device UUID to associate sync sessions instead of ephemeral usercode by @pirate in #2127
fix MAJOR bug with done callback being called twice by @mertunsall in #2130
feat: implement SDK-native rate limiting for improved reliability by @MagMueller in #2136
eval-single-task-run by @MagMueller in #2142
Fix single task run ID handling for cloud execution by @MagMueller in #2146
use raw CDP call for screenshot instead of playwright CDP session by @pirate in #2140
Files are displayed by default in done text by @mertunsall in #2151
google chat add config option by @mertunsall in #2149
Remove mem0 by @mertunsall in #2150
System prompt updates by @mertunsall in #2152
#FIX:Include system_prompt_no_thinking.md in package build by @scorpiord in #2139

Full Changelog: 0.3.3...0.4.1

Releases: browser-use/browser-use

0.5.5

What's Changed

New Contributors

Contributors

Uh oh!

0.5.4

🏥 Agent Now Auto-Recovers Crashed Pages

🐢 You can increase the default navigation and page interaction timeouts when dealing with slow network or servers:

📈 Re-use our new native retry decorators in your own projects & custom actions for more stable & consistent behavior:

💔 Upcoming Changes: What comes after Playwright-python?

Why the Switch?

The Breaking Point

What This Means for You

What's Changed

Contributors

Uh oh!

0.5.3

🕶️ Browser now falls back to incognito when given unusable user_data_dir

What's Changed

Contributors

Uh oh!

0.5.2

What's Changed

Contributors

Uh oh!

0.5.0

Ⓜ️©🅟 Native Bidirectional MCP Support

Example: Use it with Claude Desktop

What's Changed

Contributors

Uh oh!

0.4.5

What's Changed

New Contributors

Contributors

Uh oh!

0.4.4

Uh oh!

0.4.3

What's Changed

New Contributors

Contributors

Uh oh!

0.4.2

What's Changed

New Contributors

Contributors

Uh oh!

0.4.1 - BETA

Important ⚠️

What's Changed

Contributors

Uh oh!

🕶️ Browser now falls back to incognito when given unusable `user_data_dir`