# How to Set Up a Python Environment for Qwen-Agent: A Complete Installation Guide

> Learn how to set up a Python environment for Qwen-Agent with our easy guide. Install the agent, configure your API key, and start building powerful LLM applications today.

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

---

**Create a Python 3.10+ virtual environment, install `qwen-agent` with your required extras (e.g., `pip install "qwen-agent[gui,rag]"`), and configure your `DASHSCOPE_API_KEY` environment variable to start building LLM-driven agents.**

Qwen-Agent is a Python-based framework developed by the QwenLM organization that enables developers to build sophisticated LLM applications featuring tool use, retrieval-augmented generation (RAG), and multi-agent collaboration. Setting up a proper Python environment for Qwen-Agent ensures that you can isolate the framework's core dependencies from optional heavy components like GUI interfaces, document parsers, and Docker-based code execution sandboxes.

## Prerequisites for Setting Up Qwen-Agent

Before installing the package, ensure your system meets the following requirements.

### Python Version Requirements

Qwen-Agent requires **Python 3.10 or higher**. This requirement is enforced by the GUI components that depend on `gradio==5`, which utilizes modern Python type-hinting and async features not available in earlier versions.

### System Dependencies

Depending on which optional features you plan to use, you may need additional system-level tools:

- **Docker**: Required only if you intend to use the **Code Interpreter** tool, which executes Python code in a sandboxed container.
- **Node.js and uv**: Required only for **MCP (Model Context Protocol)** server integration.
- **Git**: Required if installing directly from the QwenLM/Qwen-Agent repository source.

## Step-by-Step Python Environment Setup for Qwen-Agent

Follow these commands to create an isolated environment and install Qwen-Agent with the appropriate dependencies.

### Create and Activate a Virtual Environment

Using a virtual environment prevents conflicts between Qwen-Agent's dependencies and other Python projects on your system.

```bash

# Create a virtual environment named .venv

python3 -m venv .venv

# Activate on Linux/macOS

source .venv/bin/activate

# Activate on Windows

.venv\Scripts\activate

```

### Install Core and Optional Dependencies

The [`setup.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/setup.py) file in the Qwen-Agent repository defines several **extras** that group optional functionality. You can install specific feature sets or all extras at once.

To install the core package plus GUI, RAG, Code Interpreter, and MCP support:

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

```

To install only specific extras:

```bash

# GUI only (installs gradio==5.23.1)

pip install -U "qwen-agent[gui]"

# RAG only (includes BM25 and document parsers)

pip install -U "qwen-agent[rag]"

# Core only (no extras)

pip install -U qwen-agent

```

The `extras_require` section in [`setup.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/setup.py) maps these bracket names to specific dependency lists, ensuring you only install what you need.

### Verify the Installation

Confirm that Qwen-Agent is correctly installed and check your Python version compatibility:

```bash
python -c "import qwen_agent, sys; print('Qwen-Agent version:', qwen_agent.__version__); print('Python:', sys.version)"

```

This imports the package from [`qwen_agent/__init__.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/__init__.py), which exposes the public API including the `Agent` class and `MultiAgentHub`.

## Configuring the LLM Backend

After installation, you must configure the LLM service connection. Qwen-Agent supports multiple backends including DashScope, vLLM, and Ollama.

Create a configuration file or set environment variables. The only required environment variable for DashScope is `DASHSCOPE_API_KEY`:

```bash
export DASHSCOPE_API_KEY="your-api-key-here"

```

Here is a complete example script ([`run_assistant.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/run_assistant.py)) that configures the model and creates an agent with tool use capabilities:

```python

# run_assistant.py

import os
from qwen_agent.agents import Assistant

# Model configuration for DashScope

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

# Create assistant with code interpreter tool

bot = Assistant(
    llm=llm_cfg,
    system_message="You are a helpful assistant that can run Python code.",
    function_list=["code_interpreter"],
)

# Interactive loop

messages = []
while True:
    query = input("\nUser: ")
    if query.lower() in {"exit", "quit"}:
        break
    messages.append({"role": "user", "content": query})
    for turn in bot.run(messages=messages):
        print(turn["content"], end="", flush=True)
    print()

```

Run it with:

```bash
python run_assistant.py

```

To launch a web interface instead of the terminal, use the Gradio-based GUI implemented in [`qwen_agent/gui/WebUI.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/gui/WebUI.py):

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

bot = Assistant(llm=llm_cfg, function_list=["code_interpreter"])
WebUI(bot).run()

```

## Installing Optional Features

Qwen-Agent's modular architecture allows you to install additional capabilities as needed. The [`setup.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/setup.py) file defines these extras to keep the base installation lightweight.

### GUI Components

The `gui` extra installs `gradio==5.23.1`, which powers the web interface. This is required to use `qwen_agent.gui.WebUI` or run examples like [`examples/assistant_qwen3.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/examples/assistant_qwen3.py) that launch browser-based interfaces.

### RAG and Document Processing

The `rag` extra includes BM25 retrieval algorithms, PDF parsers, and document loaders. These dependencies are defined in the `rag` section of [`setup.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/setup.py) and are required for agents that process local documents through the retrieval-augmented generation pipeline.

### Code Interpreter with Docker

The `code_interpreter` extra adds the Docker SDK to your environment. When you invoke the `code_interpreter` tool, Qwen-Agent spawns a Docker container via the Docker SDK to safely execute generated Python code. Ensure the Docker daemon is running before using this feature.

### MCP Server Integration

The `mcp` extra installs the Model Context Protocol client libraries. This feature requires Node.js and `uv` to be installed on your system to run MCP servers. Refer to the examples in [`examples/assistant_mcp_sqlite_bot.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/examples/assistant_mcp_sqlite_bot.py) for server configuration details.

## Troubleshooting Common Setup Issues

When setting up your Python environment for Qwen-Agent, you may encounter these common issues:

- **`ImportError: No module named 'dashscope'`**
  This occurs when core dependencies are missing. Ensure you installed the package with at least the base requirements: `pip install -U qwen-agent`.

- **Docker not found or permission denied**
  The Code Interpreter tool requires Docker to be installed and running. Install Docker Desktop (or `docker.io` on Linux), start the daemon, and add your user to the `docker` group.

- **`DASHSCOPE_API_KEY` not set**
  If using the DashScope backend, authentication will fail without this environment variable. Export it in your shell: `export DASHSCOPE_API_KEY=your_key`.

- **Gradio version conflicts**
  Using an older Gradio version from another project can cause GUI errors. Use the pinned version `gradio==5.23.1` installed via the `gui` extra: `pip install "qwen-agent[gui]"`.

## Summary

Setting up a Python environment for Qwen-Agent involves creating an isolated virtual environment with Python 3.10+, installing the package with your required extras from [`setup.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/setup.py), and configuring the `DASHSCOPE_API_KEY` environment variable for LLM access. The modular architecture allows you to install only necessary components—whether that's the core agent framework, Gradio-based GUIs from [`qwen_agent/gui/WebUI.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/gui/WebUI.py), RAG document processors, Docker-backed code execution, or MCP server integration.

## Frequently Asked Questions

### What Python version is required for Qwen-Agent?

Qwen-Agent requires **Python 3.10 or higher**. This requirement is enforced by the GUI components that depend on `gradio==5`, which utilizes modern Python type-hinting and async features not available in earlier versions.

### How do I install only specific optional features instead of everything?

Use the bracket syntax when installing to select specific extras defined in [`setup.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/setup.py). For example, install only the GUI components with `pip install "qwen-agent[gui]"`, or combine multiple extras like `pip install "qwen-agent[gui,rag]"`. To install the core package without any optional dependencies, simply run `pip install qwen-agent`.

### Why is Docker required for some Qwen-Agent features?

Docker is only required if you plan to use the **Code Interpreter** tool, which executes generated Python code in a sandboxed container environment. When you invoke this tool, Qwen-Agent uses the Docker SDK to spawn an isolated container for safe code execution. If you do not need code execution capabilities, you can skip Docker installation.

### How do I verify that my Qwen-Agent installation is working correctly?

Run the verification command `python -c "import qwen_agent; print(qwen_agent.__version__)"` to confirm the package imports successfully from [`qwen_agent/__init__.py`](https://github.com/QwenLM/Qwen-Agent/blob/main/qwen_agent/__init__.py). For a functional test, create a simple script that configures an `Assistant` agent with a DashScope model and attempt to run a basic query to ensure the LLM backend connection works properly.