windows-use 0.7.6
An AI Agent that interacts with Windows OS at GUI level.
Requires Python: >=3.13
Keywords: agent, ai, ai agent, automation, desktop, windows

<div align="center">

  <h1>🪟 Windows-Use</h1>
  <a href="https://pepy.tech/project/windows-use">
    <img src="https://static.pepy.tech/badge/windows-use" alt="PyPI Downloads">
  </a>
  <a href="https://github.com/CursorTouch/windows-use/blob/main/LICENSE">
    <img src="https://img.shields.io/badge/license-Apache%202.0-green" alt="License">
  </a>
  <img src="https://img.shields.io/badge/python-3.12%2B-blue" alt="Python">
  <img src="https://img.shields.io/badge/platform-Windows%207–11-blue" alt="Platform: Windows 7 to 11">
  <br>

  <a href="https://x.com/CursorTouch">
    <img src="https://img.shields.io/badge/follow-%40CursorTouch-1DA1F2?logo=twitter&style=flat" alt="Follow on Twitter">
  </a>
  <a href="https://discord.com/invite/Aue9Yj2VzS">
    <img src="https://img.shields.io/badge/Join%20on-Discord-5865F2?logo=discord&logoColor=white&style=flat" alt="Join us on Discord">
  </a>

</div>

<br>

**Windows-Use** is a powerful automation agent that interacts directly with the Windows GUI layer. It bridges the gap between AI Agents and the Windows OS to perform tasks such as opening apps, clicking buttons, typing, executing shell commands, and capturing UI state all without relying on traditional computer vision models. Enabling any LLM to perform computer automation instead of relying on specific models for it.

## 🛠️ Installation Guide

### **Prerequisites**

- Python 3.12 or higher
- [UV](https://github.com/astral-sh/uv) (or `pip`)
- Windows 7, 8, 10, or 11

### **Installation Steps**

Install the core package, then add the provider extra you need:

```bash
# With uv
uv add windows-use[anthropic]          # Anthropic Claude
uv add windows-use[openai]             # OpenAI / Azure / OpenRouter / vLLM
uv add windows-use[google]             # Google Gemini
uv add windows-use[ollama]             # Ollama (local models)
uv add windows-use[groq]               # Groq
uv add windows-use[mistral]            # Mistral
uv add windows-use[cerebras]           # Cerebras
uv add windows-use[litellm]            # LiteLLM (100+ providers)
uv add windows-use[all]                # Everything
```

Or with pip:

```bash
pip install windows-use[anthropic]      # pick your provider
pip install windows-use[openai,google]  # combine multiple
pip install windows-use[all]            # everything
```

## 🤖 Supported Providers

| Provider | Class | Extra | Default Model |
|---|---|---|---|
| Anthropic | `ChatAnthropic` | `anthropic` | `claude-3-5-sonnet-latest` |
| Google Gemini | `ChatGoogle` | `google` | `gemini-2.5-flash` |
| OpenAI | `ChatOpenAI` | `openai` | `gpt-4o` |
| Azure OpenAI | `ChatAzureOpenAI` | `openai` | — (deployment name) |
| OpenRouter | `ChatOpenRouter` | `openai` | — (model required) |
| vLLM | `ChatVLLM` | `openai` | — (model required) |
| Ollama | `ChatOllama` | `ollama` | `llama3.1` |
| Groq | `ChatGroq` | `groq` | `llama-3.3-70b-versatile` |
| Mistral | `ChatMistral` | `mistral` | `mistral-large-latest` |
| Cerebras | `ChatCerebras` | `cerebras` | `llama-3.3-70b` |
| LiteLLM | `ChatLiteLLM` | `litellm` | — (model required) |

## ⚙️ Basic Usage

### Anthropic (Recommended)

```bash
pip install windows-use[anthropic]
```

```python
from windows_use.providers.anthropic import ChatAnthropic
from windows_use.agent import Agent, Browser
from dotenv import load_dotenv

load_dotenv()

llm = ChatAnthropic(model="claude-haiku-4-5", temperature=0.2)
agent = Agent(llm=llm, browser=Browser.EDGE)
agent.invoke(query=input("Enter a query: "))
```

### Google Gemini

```bash
pip install windows-use[google]
```

```python
from windows_use.providers.google import ChatGoogle
from windows_use.agent import Agent, Browser
from dotenv import load_dotenv

load_dotenv()

llm = ChatGoogle(model="gemini-2.5-flash", temperature=0.7)
agent = Agent(llm=llm, browser=Browser.EDGE, auto_minimize=True)
agent.invoke(query=input("Enter a query: "))
```

### OpenAI

```bash
pip install windows-use[openai]
```

```python
from windows_use.providers.openai import ChatOpenAI
from windows_use.agent import Agent, Browser
from dotenv import load_dotenv

load_dotenv()

llm = ChatOpenAI(model="gpt-4o", temperature=0.2)
agent = Agent(llm=llm, browser=Browser.EDGE)
agent.invoke(query=input("Enter a query: "))
```

### Ollama (Local)

```bash
pip install windows-use[ollama]
```

```python
from windows_use.providers.ollama import ChatOllama
from windows_use.agent import Agent, Browser

llm = ChatOllama(model="qwen3-vl:235b-cloud")
agent = Agent(llm=llm, browser=Browser.EDGE, use_vision=False)
agent.invoke(query=input("Enter a query: "))
```

### Azure OpenAI

```bash
pip install windows-use[openai]
```

```python
from windows_use.providers.azure_openai import ChatAzureOpenAI
from windows_use.agent import Agent, Browser
from dotenv import load_dotenv

load_dotenv()

llm = ChatAzureOpenAI(
    deployment_name="my-gpt4o-deployment",
    azure_endpoint="https://my-resource.openai.azure.com",
)
agent = Agent(llm=llm, browser=Browser.EDGE)
agent.invoke(query=input("Enter a query: "))
```

### LiteLLM (100+ Providers)

```bash
pip install windows-use[litellm]
```

```python
from windows_use.providers.litellm import ChatLiteLLM
from windows_use.agent import Agent, Browser
from dotenv import load_dotenv

load_dotenv()

llm = ChatLiteLLM(model="anthropic/claude-3-5-sonnet-latest", temperature=0.2)
agent = Agent(llm=llm, browser=Browser.EDGE)
agent.invoke(query=input("Enter a query: "))
```

### OpenRouter

```bash
pip install windows-use[openai]
```

```python
from windows_use.providers.open_router import ChatOpenRouter
from windows_use.agent import Agent, Browser
from dotenv import load_dotenv

load_dotenv()

llm = ChatOpenRouter(model="anthropic/claude-3.5-sonnet", temperature=0.2)
agent = Agent(llm=llm, browser=Browser.EDGE)
agent.invoke(query=input("Enter a query: "))
```

## 🎛️ Agent Configuration

The `Agent` class accepts the following parameters:

| Parameter | Type | Default | Description |
|---|---|---|---|
| `llm` | `BaseChatLLM` | `None` | LLM provider instance |
| `browser` | `Browser` | `Browser.EDGE` | Browser to automate |
| `mode` | `"flash" \| "normal"` | `"normal"` | Agent prompt mode |
| `max_steps` | `int` | `25` | Maximum execution steps |
| `use_vision` | `bool` | `False` | Provide screenshots to the LLM |
| `use_annotation` | `bool` | `False` | Overlay element IDs on screenshots |
| `use_accessibility` | `bool` | `True` | Use the UI accessibility tree |
| `auto_minimize` | `bool` | `False` | Minimize the agent's console window |
| `log_to_file` | `bool` | `False` | Enable per-run file logging |
| `instructions` | `list[str]` | `None` | Custom instructions for the agent |
| `max_consecutive_failures` | `int` | `3` | Max LLM failures before aborting |
| `experimental` | `bool` | `False` | Include experimental tools |

## 🏃 Run Agent

```bash
uv run main.py
```

## ⚠️ Security

This agent can:
- Operate your computer on the behalf of the user
- Modify files and system settings
- Make irreversible changes to your system

**⚠️ STRONGLY RECOMMENDED: Deploy in a Virtual Machine or Windows Sandbox**

The project provides **NO sandbox or isolation layer**. For your safety:
- ✅ Use a Virtual Machine (VirtualBox, VMware, Hyper-V)
- ✅ Use Windows Sandbox (Windows 10/11 Pro/Enterprise)
- ✅ Use a dedicated test machine

**📖 Read the full [Security Policy](SECURITY.md) before deployment.**

## 🪪 License

This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgements

Windows-Use makes use of several excellent open-source projects that power its Windows automation features:

- [UIAutomation](https://github.com/yinkaisheng/Python-UIAutomation-for-Windows)

Huge thanks to the maintainers and contributors of these libraries for their outstanding work and open-source spirit.

## 📡 Telemetry

Windows-Use includes lightweight, privacy-friendly telemetry to help improve reliability, debug failures, and understand how the agent behaves in real environments.

You can disable telemetry by setting the environment variable:

```.env
ANONYMIZED_TELEMETRY=false
```
Or in your Python code:

```python
import os
os.environ["ANONYMIZED_TELEMETRY"] = "false"
```

## 🤝 Contributing

Contributions are welcome! Please check the [CONTRIBUTING](CONTRIBUTING) file for setup and development workflow.

Made with ❤️ by [CursorTouch](https://github.com/CursorTouch)

---

## Citation

```bibtex
@software{
  author       = {CursorTouch},
  title        = {Windows-Use: Enable AI to control Windows OS},
  year         = {2025},
  publisher    = {GitHub},
  url={https://github.com/CursorTouch/Windows-Use}
}
```