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

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) handle model-service communication and function-calling support.
• Tools – Atomic utilities in qwen_agent/tools/* (like web_search.py and 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) 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 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:

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

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

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:

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:

pip install -e .

This approach creates an editable environment where modifications to files like qwen_agent/agents/assistant.py or 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:

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.

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:

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:

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:

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 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 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—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 or qwen_agent/tools/base.py take effect without reinstallation, making this the preferred method for development and debugging.

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