# How to Install Qwen-Agent Locally: PyPI and Development Setup

> Install Qwen-Agent locally with pip for full features or clone the repo for editable development. Get started with Qwen-Agent today and unlock its capabilities.

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

---

**Install Qwen-Agent locally by running `pip install -U "qwen-agent[gui,rag,code_interpreter,mcp]"` for full functionality, or clone the repository and use `pip install -e .` for editable development mode.**

Qwen-Agent is a modular framework developed by **QwenLM** for building LLM-driven assistants with support for tool use, planning, memory, and Gradio-based GUIs. This guide explains how to install Qwen-Agent locally from PyPI or source code, configure your model service, and verify the installation with working examples.

## Understanding the Qwen-Agent Architecture

Before installing, it helps to understand the framework’s three-layer architecture as implemented in the `QwenLM/Qwen-Agent` repository:

- **LLM back-ends** – Wrapper classes in `qwen_agent/llm/*` (such as [`qwen_agent/llm/qwen_dashscope.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/llm/qwen_dashscope.py)) handle model-service communication and function-calling support.
- **Tools** – Atomic utilities in `qwen_agent/tools/*` (like [`web_search.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/web_search.py) and [`code_interpreter.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/code_interpreter.py)) inherit from `BaseTool` and register via the `@register_tool` decorator.
- **Agents** – High-level orchestrators in `qwen_agent/agents/*` (such as [`assistant.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/assistant.py)) combine an LLM with tools and optional memory.

Additional components include the **GUI** (`qwen_agent/gui/WebUI`), pluggable **memory** back-ends, and **MCP** (Model-Context-Protocol) support via `qwen_agent/mcp/*`.

## Install Qwen-Agent from PyPI

The fastest way to install Qwen-Agent locally is via the single-command PyPI installation. The package defines optional extras in [`setup.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/setup.py) that enable specific capabilities:

- **`[gui]`** – Installs Gradio for the WebUI interface.
- **`[rag]`** – Enables retrieval-augmented generation features.
- **`[code_interpreter]`** – Activates Docker-based sandboxed Python execution.
- **`[mcp]`** – Adds Model-Context-Protocol tool support.

Install everything at once:

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

```

For a minimal installation with only the core framework, omit the extras:

```bash
pip install -U qwen-agent

```

## Install from Source for Development

For contributors or developers who need to modify the source code, use an **editable installation** that reflects changes instantly without reinstallation:

```bash
git clone https://github.com/QwenLM/Qwen-Agent.git
cd Qwen-Agent
pip install -e ."[gui,rag,code_interpreter,mcp]"

```

To install the minimal development version without extras:

```bash
pip install -e .

```

This approach creates an editable environment where modifications to files like [`qwen_agent/agents/assistant.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/agents/assistant.py) or [`qwen_agent/tools/web_search.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/tools/web_search.py) take effect immediately.

## Configure Your Model Service

Qwen-Agent does not ship with a built-in LLM; it connects to any OpenAI-compatible endpoint such as DashScope, vLLM, or Ollama. Configure access using environment variables or the `llm_cfg` dictionary.

Set your DashScope API key:

```bash
export DASHSCOPE_API_KEY=your_key_here

```

Alternatively, specify the endpoint directly in your Python code via the `llm_cfg` parameter when instantiating agents from [`qwen_agent/agents/assistant.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/agents/assistant.py).

## Verify Your Installation with Working Examples

Test your local installation by running these progressive examples that exercise the core framework, GUI, and tool integrations.

### Minimal Agent Setup (Core Only)

This example uses only the base `Assistant` class from `qwen_agent/agents` with no optional tools:

```python
from qwen_agent.agents import Assistant
from qwen_agent.utils.output_beautify import typewriter_print

# LLM configuration – modify for your endpoint

llm_cfg = {
    "model": "qwen-max-latest",
    "model_type": "qwen_dashscope",   # reads DASHSCOPE_API_KEY automatically

    "generate_cfg": {"top_p": 0.8},
}

# Create a plain Assistant agent

bot = Assistant(llm=llm_cfg)

# Simple chat loop

messages = []
while True:
    query = input("\nYou: ")
    messages.append({"role": "user", "content": query})
    print("Agent:")
    for chunk in bot.run(messages=messages):
        typewriter_print(chunk, "")

```

### Launch the Gradio Web UI

Requires the `[gui]` extra installed. This opens a browser interface at `http://127.0.0.1:7860`:

```python
from qwen_agent.agents import Assistant
from qwen_agent.gui import WebUI

llm_cfg = {
    "model": "qwen-max-latest",
    "model_type": "qwen_dashscope",
}
bot = Assistant(llm=llm_cfg)

# Start the web server

WebUI(bot).run()

```

### Enable the Code Interpreter Tool

Requires Docker running on your host and the `[code_interpreter]` extra. This example demonstrates tool registration via the `function_list` parameter:

```python
tools = ["code_interpreter"]          # register built-in tool

bot = Assistant(llm=llm_cfg, function_list=tools)

# Example prompt that triggers code execution

messages = [{"role": "user", "content": "Plot a sine wave using matplotlib."}]
for out in bot.run(messages=messages):
    print(out)

```

For a complete end-to-end demonstration, see [`examples/assistant_qwen3.5.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/examples/assistant_qwen3.5.py) in the repository, which shows full installation verification with the latest Qwen-3.5 model.

## Summary

- **PyPI Installation**: Use `pip install -U "qwen-agent[gui,rag,code_interpreter,mcp]"` to install Qwen-Agent locally with all optional features.
- **Development Setup**: Clone the repository and run `pip install -e ."[gui,rag,code_interpreter,mcp]"` for an editable environment.
- **Model Configuration**: Export `DASHSCOPE_API_KEY` or customize the `llm_cfg` dictionary to connect to your LLM endpoint.
- **Core Components**: The framework centers on [`qwen_agent/agents/assistant.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/agents/assistant.py) for agents, `qwen_agent/tools/` for utilities, and `qwen_agent/gui/` for interfaces.
- **Verification**: Test with a minimal script, then add the WebUI (`WebUI` class) or code interpreter tools as needed.

## Frequently Asked Questions

### Do I need to install a local LLM to run Qwen-Agent?

No. According to the `QwenLM/Qwen-Agent` source code, the framework operates as a client to remote model services. It communicates via standard APIs with DashScope, vLLM, Ollama, or any OpenAI-compatible endpoint, so you only need to configure the connection through environment variables or the `llm_cfg` parameter.

### What is the difference between installing with and without extras?

The base `qwen-agent` package provides the core agent architecture, LLM wrappers, and memory systems. Installing with extras like `[gui]`, `[rag]`, `[code_interpreter]`, or `[mcp]` pulls additional dependencies defined in [`setup.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/setup.py)—such as Gradio for web interfaces, Docker SDK for sandboxed code execution, or MCP libraries for protocol support.

### How do I troubleshoot import errors after installation?

Ensure you installed the specific extras required for your use case. For example, `from qwen_agent.gui import WebUI` fails if you omitted the `[gui]` extra. If running the code interpreter tool, verify Docker is installed and running on your system, as the `code_interpreter` tool relies on Docker for sandboxed execution.

### Can I modify the source code and test changes immediately?

Yes. When you install Qwen-Agent locally using `pip install -e .`, Python references the source files directly. Changes to modules like [`qwen_agent/agents/assistant.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/agents/assistant.py) or [`qwen_agent/tools/base.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/tools/base.py) take effect without reinstallation, making this the preferred method for development and debugging.