How to Install Qwen Code CLI: Step-by-Step Tutorial for Terminal AI Coding Agent

Prerequisites

Before installing Qwen Code CLI (the official terminal-based AI coding agent powered by Qwen models), ensure you have the following:

• Node.js version 20 or higher (recommended: latest LTS). Download from nodejs.org.
• A terminal or command prompt with administrative privileges on Windows.
• Internet connection for downloading packages and models.
• Optional but recommended: Git (for manual source installation) and Homebrew on macOS/Linux.

Verify Node.js installation:

node --version
npm --version

Expected output shows versions like v20.x.x or higher.

Step 1: Choose Your Installation Method

Qwen Code CLI offers multiple installation paths. The quick install script is recommended for most users as it handles dependencies automatically.

Quick Install (Recommended)

Linux / macOS:

bash -c "$(curl -fsSL https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/install-qwen.sh)"

Windows (Run Command Prompt as Administrator):

curl -fsSL -o %TEMP%\install-qwen.bat https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/install-qwen.bat && %TEMP%\install-qwen.bat

After running, restart your terminal to refresh the PATH.

Step 2: Manual Installation via npm

If you prefer manual control:

npm install -g @qwen-code/qwen-code@latest

This installs the qwen command globally.

On macOS/Linux with sudo (if permission issues occur):

sudo npm install -g @qwen-code/qwen-code@latest

Step 3: Install via Homebrew (macOS & Linux)

brew install qwen-code

Step 4: Verify the Installation

Run the following command to confirm successful installation:

qwen --version

You should see output similar to:

Qwen Code CLI v0.x.x

Step 5: First Launch and Authentication

Launch the interactive CLI:

qwen

On first run, the CLI will prompt you to authenticate with your Qwen account (opens browser for one-click login). After logging in, it applies default settings and enters the interactive terminal UI.

Navigate to your project directory first for best results:

cd /path/to/your/project
qwen

Inside the session, use commands like /help, /model to switch models, or reference files with @filename.

Step 6: Manual Installation from Source (Advanced)

For developers wanting the latest unreleased changes:

git clone https://github.com/QwenLM/qwen-code.git
cd qwen-code
npm install
npm install -g .

Then verify with qwen --version.

Common Issues & Troubleshooting

• Command 'qwen' not found: Restart your terminal or run hash -r (Linux/macOS). On Windows, close and reopen Command Prompt. Ensure Node.js global bin directory is in your PATH.

• Permission errors during npm install: Use sudo on Linux/macOS or run Command Prompt as Administrator on Windows.

• Node.js version too old: Upgrade to Node 20+ using nvm or official installer.

• Network issues with Aliyun assets: Try the npm method as fallback.

• Installation fails on Termux or certain Linux distros: Use --ignore-scripts flag: npm install -g @qwen-code/qwen-code@latest --ignore-scripts.

• Authentication not working: Ensure your browser allows pop-ups and you have a valid Qwen account.

For persistent issues, check the official GitHub repository: https://github.com/QwenLM/qwen-code.

Next Steps

• Explore the interactive UI: Type /help for available slash commands.
• Try agentic coding: Ask the CLI to refactor code, explain files, or automate tasks using natural language.
• Configure models: Use /model to select Qwen3-Coder or other supported backends (including local Ollama).
• Integrate with VS Code: Install the Qwen Code Companion extension for seamless editor integration.
• Customize settings: Edit ~/.qwen/settings.json for themes, default models, and advanced options.

Now you're ready to use Qwen Code CLI as a powerful AI pair programmer directly in your terminal. Start with simple prompts like "Explain this codebase" or "Refactor this function for better performance" inside your project folder.

Happy coding!