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

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.

# 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 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:

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

To install only specific extras:

# 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 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:

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, 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:

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

Here is a complete example script (run_assistant.py) that configures the model and creates an agent with tool use capabilities:

# 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:

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:

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 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 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 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 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, 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, 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. 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. 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}