Skip to content

Open-source Python library for AI browser agents, plus Browser Use Cloud: stealth browsers and a hosted agent API.

add revamped readme with new stylization and demos

Alezander949b02468dd64
diff --git a/README.md b/README.md
index b2b8a61d1..ee0aba2f8 100644
--- a/README.md
+++ b/README.md
@@ -1,23 +1,20 @@
<picture>
- <source media="(prefers-color-scheme: dark)" srcset="./static/browser-use-dark.png">
- <source media="(prefers-color-scheme: light)" srcset="./static/browser-use.png">
- <img alt="Shows a black Browser Use Logo in light color mode and a white one in dark color mode." src="./static/browser-use.png" width="full">
+ <source media="(prefers-color-scheme: light)" srcset="https://github.com/user-attachments/assets/2ccdb752-22fb-41c7-8948-857fc1ad7e24"">
+ <source media="(prefers-color-scheme: dark)" srcset="https://github.com/user-attachments/assets/774a46d5-27a0-490c-b7d0-e65fcbbfa358">
+ <img alt="Shows a black Browser Use Logo in light color mode and a white one in dark color mode." src="https://github.com/user-attachments/assets/774a46d5-27a0-490c-b7d0-e65fcbbfa358" width="full">
</picture>
-<h1 align="center">Enable AI to control your browser</h1>
-
-[![Docs](https://img.shields.io/badge/Docs-๐Ÿ“•-blue?style=for-the-badge)](https://docs.browser-use.com)
-[![Browser-use cloud](https://img.shields.io/badge/Browser_Use_Cloud-โ˜๏ธ-blue?style=for-the-badge&logo=rocket&logoColor=white)](https://cloud.browser-use.com)
-
-[![Discord](https://img.shields.io/discord/1303749220842340412?color=7289DA&label=Discord&logo=discord&logoColor=white)](https://link.browser-use.com/discord)
-[![Twitter Follow](https://img.shields.io/twitter/follow/Gregor?style=social)](https://x.com/intent/user?screen_name=gregpr07)
-[![Twitter Follow](https://img.shields.io/twitter/follow/Magnus?style=social)](https://x.com/intent/user?screen_name=mamagnus00)
-[![Merch store](https://img.shields.io/badge/Merch_store-๐Ÿ‘•-blue)](https://browsermerch.com)
-[![Weave Badge](https://img.shields.io/endpoint?url=https%3A%2F%2Fapp.workweave.ai%2Fapi%2Frepository%2Fbadge%2Forg_T5Pvn3UBswTHIsN1dWS3voPg%2F881458615&labelColor=#EC6341)](https://app.workweave.ai/reports/repository/org_T5Pvn3UBswTHIsN1dWS3voPg/881458615)
-
-
+<div align="center">
+ <picture>
+ <source media="(prefers-color-scheme: light)" srcset="https://github.com/user-attachments/assets/9955dda9-ede3-4971-8ee0-91cbc3850125"">
+ <source media="(prefers-color-scheme: dark)" srcset="https://github.com/user-attachments/assets/6797d09b-8ac3-4cb9-ba07-b289e080765a">
+ <img alt="The AI browser agent." src="https://github.com/user-attachments/assets/6797d09b-8ac3-4cb9-ba07-b289e080765a" width="400">
+ </picture>
+</div>
+</br>
+<div align="center">
<!-- Keep these links. Translations will automatically update with the README. -->
[Deutsch](https://www.readme-i18n.com/browser-use/browser-use?lang=de) |
@@ -29,30 +26,64 @@
[ะ ัƒััะบะธะน](https://www.readme-i18n.com/browser-use/browser-use?lang=ru) |
[ไธญๆ–‡](https://www.readme-i18n.com/browser-use/browser-use?lang=zh)
+</div>
-# ๐Ÿค– Quickstart
+---
-With uv (Python>=3.11):
+<div align="center">
+<a href="#demos"><img src="https://media.browser-use.tools/badges/demos" alt="Demos"></a>
+<img width="16" height="1" alt="">
+<a href="https://docs.browser-use.com"><img src="https://media.browser-use.tools/badges/docs" alt="Docs"></a>
+<img width="16" height="1" alt="">
+<a href="https://browser-use.com/posts"><img src="https://media.browser-use.tools/badges/blog" alt="Blog"></a>
+<img width="16" height="1" alt="">
+<a href="https://browsermerch.com"><img src="https://media.browser-use.tools/badges/merch" alt="Merch"></a>
+<img width="100" height="1" alt="">
+<a href="https://github.com/browser-use/browser-use"><img src="https://media.browser-use.tools/badges/github" alt="Github Stars"></a>
+<img width="4" height="1" alt="">
+<a href="https://x.com/intent/user?screen_name=browser_use"><img src="https://media.browser-use.tools/badges/twitter" alt="Twitter"></a>
+<img width="4 height="1" alt="">
+<a href="https://link.browser-use.com/discord"><img src="https://media.browser-use.tools/badges/discord" alt="Discord"></a>
+<img width="4" height="1" alt="">
+<a href="https://cloud.browser-use.com"><img src="https://media.browser-use.tools/badges/cloud" height="48" alt="Browser-Use Cloud"></a>
+</div>
-```bash
-# We ship every day - use the latest version!
-uv pip install browser-use
-```
+</br>
-Download chromium using playwright's shortcut:
+# ๐Ÿค– LLM Quickstart
+1. Clone this repo
+2. Direct your favorite coding agent (Cursor, ClaudeS, etc) to [Agents.md](https://docs.browser-use.com/llms-full.txt)
+3. Prompt away!
+
+<br/>
+
+# ๐Ÿ‘‹ Human Quickstart
+
+**1. Create environment with [uv](https://docs.astral.sh/uv/) (Python>=3.11):**
```bash
-uvx playwright install chromium --with-deps --no-shell
+uv venv --python 3.12
+source .venv/bin/activate
```
-Get your API key from [Browser Use Cloud](https://cloud.browser-use.com/dashboard/api) and add it to your `.env` file (new signups get $10 free credits via OAuth or $1 via email):
-
+**2. Install Browser-Use package:**
```bash
+# We ship every day - use the latest version!
+uv pip install browser-use
+```
+
+**3. Get your API key from [Browser Use Cloud](https://cloud.browser-use.com/dashboard/api) and add it to your `.env` file (new signups get $10 free credits):**
+```
+# .env
BROWSER_USE_API_KEY=your-key
```
-Run your first agent:
+**4. Download chromium using playwright's shortcut:**
+```bash
+uvx playwright install chromium --with-deps --no-shell
+```
+**5. Run your first agent:**
```python
from browser_use import Agent, ChatBrowserUse
@@ -63,68 +94,67 @@ agent = Agent(
agent.run_sync()
```
-Check out the [library docs](https://docs.browser-use.com) and [cloud docs](https://docs.cloud.browser-use.com) for more settings.
-
+Check out the [library docs](https://docs.browser-use.com) for more!
-## Stealth Browser Infrastructure
+<br/>
-Want to bypass Cloudflare, or any other anti-bot protection?
+# Stealth Browser Infrastructure
-Simply go to [Browser Use Cloud](https://docs.cloud.browser-use.com) grab a `BROWSER_USE_API_KEY` and use the `use_cloud` parameter.
+Want to bypass anti-bot detection or run a fleet of agents on the cloud? Use our hosted stealth browsers.
+**Follow steps 1-3 above, and pass in a Browser made with the `use_cloud` parameter.**
```python
-from browser_use import Agent, Browser
-from browser_use import ChatBrowserUse
+from browser_use import Agent, Browser, ChatBrowserUse
-# Use Browser-Use cloud browser service
browser = Browser(
use_cloud=True, # Automatically provisions a cloud browser
)
-
agent = Agent(
- task="Your task here",
+ task="Find the number of stars of the browser-use repo",
llm=ChatBrowserUse(),
browser=browser,
)
+agent.run_sync()
```
+**Optional: Follow the link in the console to watch the remote browser.**
+
+Check out the [cloud docs](https://docs.cloud.browser-use.com) for more!
+<br/>
# Demos
-[Task](https://github.com/browser-use/browser-use/blob/main/examples/use-cases/shopping.py): Add grocery items to cart, and checkout.
-[![AI Did My Groceries](https://github.com/user-attachments/assets/a0ffd23d-9a11-4368-8893-b092703abc14)](https://www.youtube.com/watch?v=L2Ya9PYNns8)
+### ๐Ÿ“‹ Form-Filling
+#### Task = "Fill in this job application with my resume and information."
+![Job Application Demo](https://github.com/user-attachments/assets/57865ee6-6004-49d5-b2c2-6dff39ec2ba9)
+[Example code โ†—](https://github.com/browser-use/browser-use/blob/main/examples/use-cases/apply_to_job.py)
-<br/><br/>
+### ๐ŸŽ Grocery-Shopping
+#### Task = "Put this list of items into my instacart."
-[Task](https://github.com/browser-use/browser-use/blob/main/examples/use-cases/find_and_apply_to_jobs.py): Read my CV & find ML jobs, save them to a file, and then start applying for them in new tabs, if you need help, ask me.
+https://github.com/user-attachments/assets/a6813fa7-4a7c-40a6-b4aa-382bf88b1850
-![Job Application Demo](https://github.com/user-attachments/assets/57865ee6-6004-49d5-b2c2-6dff39ec2ba9)
+[Example code โ†—](https://github.com/browser-use/browser-use/blob/main/examples/use-cases/buy_groceries.py)
-<br/><br/>
-See [more examples](https://docs.browser-use.com/examples) and give us a star!
+### ๐Ÿ’ป Personal-Assistant.
+#### Task = "Help me find parts for a custom PC."
+https://github.com/user-attachments/assets/ac34f75c-057a-43ef-ad06-5b2c9d42bf06
-<br/><br/>
-## MCP Integration
+[Example code โ†—](https://github.com/browser-use/browser-use/blob/main/examples/use-cases/pcpartpicker.py)
-This gives Claude Desktop access to browser automation tools for web scraping, form filling, and more. See the [MCP docs](https://docs.browser-use.com/customize/mcp-server).
-```json
-{
- "mcpServers": {
- "browser-use": {
- "command": "uvx",
- "args": ["browser-use[cli]", "--mcp"],
- "env": {
- "OPENAI_API_KEY": "sk-..."
- }
- }
- }
-}
-```
+
+### ๐Ÿ’กSee [more examples here โ†—](https://docs.browser-use.com/examples) and give us a star!
+
+<br/>
+
+## Integrations, hosting, custom tools, MCP, and more on our [Docs โ†—](https://docs.browser-use.com)
+
+<br/>
<div align="center">
@@ -133,10 +163,9 @@ This gives Claude Desktop access to browser automation tools for web scraping, f
<img src="https://github.com/user-attachments/assets/06fa3078-8461-4560-b434-445510c1766f" width="400"/>
[![Twitter Follow](https://img.shields.io/twitter/follow/Magnus?style=social)](https://x.com/intent/user?screen_name=mamagnus00)
+&emsp;&emsp;&emsp;
[![Twitter Follow](https://img.shields.io/twitter/follow/Gregor?style=social)](https://x.com/intent/user?screen_name=gregpr07)
</div>
-<div align="center">
-Made with โค๏ธ in Zurich and San Francisco
- </div>
+<div align="center"> Made with โค๏ธ in Zurich and San Francisco </div>