# System Requirements for Running Qwen-Agent: Complete Setup Guide

> Discover the exact system requirements for running Qwen-Agent. Learn about necessary Python versions, OS compatibility, GPU needs, and Docker for a smooth setup.

- Repository: [Qwen/Qwen-Agent](https://github.com/qwenlm/Qwen-Agent)
- Tags: how-to-guide
- Published: 2026-03-09

---

**TLDR:** To run Qwen-Agent, you need **Python 3.10 or newer**, a Linux/macOS/Windows operating system, and **pip** to install core dependencies like `dashscope>=1.11.0`, `pydantic>=2.3.0`, and `openai`. Optional features require additional components: **Docker** for the sandboxed code interpreter, **CUDA-enabled GPUs** for local model inference, and specific extras installed via `pip install "qwen-agent[gui,rag]"`.

Qwen-Agent is a Python-based framework developed by QwenLM that enables large-language-model (LLM) agents with capabilities including tool use, planning, memory, RAG, and code interpretation. Understanding the **system requirements for running Qwen-Agent** ensures you can deploy agents either via API endpoints like DashScope or run them locally with advanced features. The framework's modular architecture allows you to install only the components you need, from minimal core functionality to full GUI and interpreter support.

## Software and Operating System Requirements

Qwen-Agent runs on any modern operating system provided you meet the Python version prerequisite.

### Operating System Compatibility

While the repository is primarily tested in Linux CI environments, Qwen-Agent functions correctly on **macOS** and **Windows** systems as long as Python 3.10+ and native dependencies are available.

### Python Version Requirement

According to the [README.md](https://github.com/QwenLM/Qwen-Agent/blob/main/README.md#L45) installation notes, the framework explicitly requires **Python 3.10 or newer**. This requirement stems from the Gradio 5 GUI dependency and modern CPython features used by optional packages. Earlier Python versions will fail during installation or runtime when attempting to launch the web interface.

## Hardware and Infrastructure Requirements

### Compute Resources

For basic operation using API-based models (e.g., DashScope, OpenAI-compatible endpoints), Qwen-Agent runs on standard CPUs with minimal RAM requirements. However, if you intend to run Qwen-3-VL or other large models locally, you need a **CUDA-enabled GPU** with appropriate drivers installed.

### Docker for Code Execution

The built-in **Code Interpreter** tool requires **Docker** to be installed and running. As implemented in [`qwen_agent/tools/code_interpreter.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/tools/code_interpreter.py), this tool launches sandboxed containers to safely execute generated code. Without Docker, code execution features will be unavailable, though the rest of the framework remains functional.

## Dependency Structure and Installation

Dependencies are declared in [`setup.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/setup.py) and split between core requirements and optional feature groups.

### Core Dependencies

The `install_requires` section in [`setup.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/setup.py) (lines 58-70) mandates these packages for all installations:

- `dashscope>=1.11.0`
- `eval_type_backport`
- `json5`, `jsonlines`, `jsonschema`
- `openai`
- `pydantic>=2.3.0`
- `requests`, `tiktoken`, `pillow`, `python-dotenv`

### Optional Extras

You can install specific capability groups using bracket syntax in pip. The `extras_require` section in [`setup.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/setup.py) (lines 73-118) defines:

- **[rag]**: Document processing tools including `rank_bm25`, `jieba`, `beautifulsoup4`, `pdfminer.six`, `pdfplumber`, `python-docx`, `python-pptx`, `pandas`
- **[mcp]**: Model Context Protocol support via `mcp`
- **[python_executor]**: Safe code execution with `pebble`, `multiprocess`, `timeout_decorator`, `sympy`, `numpy`, `scipy`
- **[code_interpreter]**: Jupyter kernel integration requiring `jupyter>=1.0.0`, `fastapi>=0.103.1`, `uvicorn>=0.23.2`, `anyio>=3.7.1`
- **[gui]**: Gradio web interface requiring `gradio==5.23.1`, `pydantic==2.9.2`, `pydantic-core==2.23.4`, `modelscope_studio==1.1.7`

## Installation and Verification

Install the framework with your required feature set using pip commands.

### Basic Installation

For minimal functionality without GUI or advanced tools:

```bash
pip install -U qwen-agent

```

### Full Feature Installation

For most use cases including the GUI, RAG, code interpreter, and MCP:

```bash
pip install -U "qwen-agent[gui,rag,code_interpreter,mcp]"

```

### Verify Installation with a Test Agent

Create a minimal agent to validate your setup. This example uses the `Assistant` class from [`qwen_agent/agent.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/agent.py) with DashScope configuration:

```python
from qwen_agent.agents import Assistant

# Configure LLM (reads DASHSCOPE_API_KEY from environment)

llm_cfg = {
    "model": "qwen-max-latest",
    "model_type": "qwen_dashscope",
    "generate_cfg": {"top_p": 0.8},
}

# Initialize assistant

assistant = Assistant(llm=llm_cfg)

# Test interaction

messages = [{"role": "user", "content": "Hello, what are your system requirements?"}]
for chunk in assistant.run(messages=messages):
    print(chunk, end="", flush=True)

```

### Launch the Gradio GUI

If you installed the `[gui]` extra, start the web interface defined in [`qwen_agent/gui/__init__.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/gui/__init__.py):

```bash
python -m qwen_agent.gui --port 7860

```

Access the interface at `http://localhost:7860` to interact with agents visually.

## Summary

- **Python 3.10+** is mandatory, particularly for the Gradio 5 GUI components referenced in the repository README
- **OS flexibility**: Linux (primary), macOS, and Windows supported
- **Core dependencies** are automatically installed via pip from [`setup.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/setup.py) requirements (lines 58-70)
- **Docker** is required only for the sandboxed code interpreter functionality in [`qwen_agent/tools/code_interpreter.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/tools/code_interpreter.py)
- **GPU/CUDA** is optional and only necessary for local model inference, not API-based usage
- **Modular extras** allow selective installation of RAG, MCP, Python execution, and GUI components via `pip install "qwen-agent[extra_name]"` as defined in [`setup.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/setup.py) lines 73-118

## Frequently Asked Questions

### Does Qwen-Agent work on Windows?

Yes. While the repository is tested primarily on Linux CI environments, Qwen-Agent runs on Windows provided you install **Python 3.10 or newer** and all required dependencies. The Gradio GUI and core agent functionality work cross-platform, though you may need Windows-specific paths if using local file-based tools.

### Is a GPU required to run Qwen-Agent?

No. A **GPU is optional**. If you use API endpoints like DashScope or other OpenAI-compatible services, the framework operates entirely on CPU. You only need a **CUDA-enabled GPU** if you choose to run large language models such as Qwen-3-VL locally on your machine.

### Why does the Code Interpreter require Docker?

The Code Interpreter tool, as implemented in [`qwen_agent/tools/code_interpreter.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/tools/code_interpreter.py), uses Docker containers to create isolated, sandboxed environments for executing generated Python code. This prevents malicious or erroneous code from affecting your host system. Without Docker installed and running, the code interpreter feature will fail while other agent capabilities remain available.

### Can I install Qwen-Agent without the GUI dependencies?

Yes. Run `pip install qwen-agent` to install only the core dependencies defined in [`setup.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/setup.py) under `install_requires`. This minimal installation excludes Gradio, specific Pydantic version locks, and ModelScope Studio, making it suitable for server deployments or headless environments where you interact with agents programmatically through the classes in [`qwen_agent/agent.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/agent.py) rather than through a web interface.