CARVIEW |
Navigation Menu
-
Notifications
You must be signed in to change notification settings - Fork 7.6k
Releases: browser-use/browser-use
0.5.5
53c4591
Compare
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
Assets 2
0.5.4
d04d592
Compare
π₯ 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 /SingletonLock
ed 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 ifload
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 incognitouser_data_dir=None
and any providedstorage_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:
- https://docs.browser-use.com/customize/browser-settings#playwright-timing-settings
- https://docs.browser-use.com/customize/browser-settings#timeout
- https://playwright.dev/python/docs/api/class-browsercontext#browser-context-set-default-navigation-timeout
π 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 justnavigate(url: str, new_tab: bool, timeout_ms: int)
by @pirate
Full Changelog: 0.5.3...0.5.4
Assets 2
0.5.3
Compare
πΆοΈ 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_dir
s 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_dir
s 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.
- πͺ https://docs.browser-use.com/customize/browser-settings#storage-state
- π―ββοΈ https://docs.browser-use.com/customize/real-browser#parallel-agents%2C-same-profile%2C-different-browsers
- π https://playwright.dev/python/docs/api/class-browsercontext#browser-context-storage-state
- π https://docs.browser-use.com/customize/sensitive-data
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
Assets 2
0.5.2
Compare
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
Assets 2
0.5.0
Compare
βοΈ Β©π
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 π

- https://docs.browser-use.com/customize/mcp-client
- https://docs.browser-use.com/customize/mcp-server
- https://docs.browser-use.com/cli
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
Assets 3
0.4.5
e328b91
Compare
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
Assets 2
0.4.4
4038596
Compare
new release 0.4.4 (#2283)
Assets 2
0.4.3
2559c2a
Compare
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
Assets 2
0.4.2
Compare
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
Full Changelog: 0.4.1...0.4.2
Assets 2
0.4.1 - BETA
843e0c6
Compare
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