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

Learn how to install Qwen Code CLI, the open-source AI coding agent for your terminal. Step-by-step instructions for npm, quick install script, Homebrew, and troubleshooting on Windows, macOS, and Linux.

Canonical URL: https://a2a-mcp.org/blog/qwen-cli-install

Language: en

Published: 2026-04-07

Updated: 2026-04-07

## 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](https://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**:

```bash
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
bash -c "$(curl -fsSL https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/install-qwen.sh)"
```

**Windows (Run Command Prompt as Administrator)**:

```cmd
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:

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

This installs the `qwen` command globally.

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

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

## Step 3: Install via Homebrew (macOS & Linux)

```bash
brew install qwen-code
```

## Step 4: Verify the Installation

Run the following command to confirm successful installation:

```bash
qwen --version
```

You should see output similar to:

```
Qwen Code CLI v0.x.x
```

## Step 5: First Launch and Authentication

Launch the interactive CLI:

```bash
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:

```bash
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:

```bash
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!