Installation

Install Qwen Code using npm, Homebrew, or our quick install script

Prerequisites

Before installing Qwen Code, ensure you have the following:

Node.js

Version 20 or later is required. Download from nodejs.org.

Terminal

A modern terminal that supports ANSI colors and UTF-8 encoding.

Check your Node.js version with node --version. If you need to manage multiple Node.js versions, consider using nvm.

Quick Install (Recommended)

The fastest way to get started is with our installation script. It automatically detects your platform and installs Qwen Code globally.

Linux / macOS

curl -fsSL https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/install-qwen.sh | bash

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

Windows users: Run the command prompt as Administrator to ensure proper installation.

After Installation

Restart your terminal to ensure environment variables take effect:

# Close and reopen your terminal, then verify the installation
qwen --version

Manual Installation

If you prefer manual installation or need more control, use one of these methods:

NPM (All Platforms)

Install globally using npm:

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

Verify the installation:

qwen --version

The global installation makes the qwen command available system-wide.

Homebrew (macOS, Linux)

If you use Homebrew package manager:

brew install qwen-code

Verify the installation:

qwen --version

Package Manager Comparison

Method	Platforms	Auto-Updates	Advantages
Install Script	All	✅	Fastest, platform-specific
NPM	All	✅	Standard Node.js workflow
Homebrew	macOS, Linux	✅	Integrates with Homebrew updates

Updating Qwen Code

Keep Qwen Code up to date to get the latest features and bug fixes.

NPM

npm update -g @qwen-code/qwen-code

brew upgrade qwen-code

# Re-run the install script
curl -fsSL https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/install-qwen.sh | bash

Qwen Code automatically checks for updates when you run it. You’ll see a notification if a new version is available.

Installation Verification

After installation, verify everything is working correctly:

1. Check version

   qwen --version
   

   You should see output like: @qwen-code/qwen-code 0.12.1

2. Test help command

   qwen --help
   

   This displays all available CLI options and commands.

3. Launch interactive mode

   qwen
   

   This starts the interactive terminal UI. Press Ctrl+C or type /exit to quit.

Development Installation

If you want to contribute to Qwen Code or run from source:

1. Clone the repository

   git clone https://github.com/QwenLM/qwen-code.git
   cd qwen-code
   
2. Install dependencies

   npm install
   

   This installs all packages in the monorepo workspace.

3. Build the project

   npm run build
   

   This compiles TypeScript and bundles all packages.

4. Run from source

   npm start
   

   Or for development mode with hot reload:

   npm run dev
   

For development, use Node.js version ~20.19.0 with nvm for best compatibility.

Troubleshooting

Common Issues

Command not found: qwen

Issue: The qwen command is not recognized after installation.

Solutions:

1. Restart your terminal to reload PATH variables
2. Check if npm global bin is in your PATH:
   npm config get prefix
   
   The bin directory should be in your system PATH.
3. For npm installations, try:
   npm install -g @qwen-code/qwen-code --force
   

Permission denied (EACCES)

Issue: NPM installation fails with permission errors.

Solutions:

1. On macOS/Linux: Use a Node version manager like nvm (recommended)
2. Alternative: Configure npm to use a different directory:
   mkdir ~/.npm-global
   npm config set prefix '~/.npm-global'
   echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.profile
   source ~/.profile
   
3. Not recommended: Use sudo (can cause permission issues later)

Node.js version mismatch

Issue: Error about unsupported Node.js version.

Solutions:

1. Check your Node.js version:
   node --version
   
2. Update to Node.js 20 or later from nodejs.org
3. Or use nvm to install the correct version:
   nvm install 20
   nvm use 20
   

Windows installation issues

Issue: Installation fails on Windows.

Solutions:

1. Run Command Prompt or PowerShell as Administrator
2. Ensure Windows Build Tools are installed:
   npm install --global windows-build-tools
   
3. Use the Windows install script instead of npm
4. Consider using WSL2 (Windows Subsystem for Linux) for a Linux environment

Getting Help

If you continue to experience issues:

GitHub Issues

Search existing issues or create a new one

Discord Community

Ask for help in our community Discord

Uninstallation

If you need to remove Qwen Code:

NPM

npm uninstall -g @qwen-code/qwen-code

brew uninstall qwen-code

To also remove configuration files:

rm -rf ~/.qwen

Removing ~/.qwen deletes all your settings, authentication tokens, and session history.

Next Steps

Now that Qwen Code is installed, set up authentication to start using it:

Configure Authentication

Set up Qwen OAuth or API key authentication →