System Requirements for Running Qwen-Agent: Complete Setup Guide

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 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, 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 and split between core requirements and optional feature groups.

Core Dependencies

The install_requires section in 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 (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:

pip install -U qwen-agent

Full Feature Installation

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

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 with DashScope configuration:

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:

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 requirements (lines 58-70)
• Docker is required only for the sandboxed code interpreter functionality in 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 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, 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 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 rather than through a web interface.

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