> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/QwenLM/qwen-code/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

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

## Prerequisites

Before installing Qwen Code, ensure you have the following:

<CardGroup cols={2}>
  <Card title="Node.js" icon="node-js">
    **Version 20 or later** is required. Download from [nodejs.org](https://nodejs.org/en/download).
  </Card>

  <Card title="Terminal" icon="terminal">
    A modern terminal that supports ANSI colors and UTF-8 encoding.
  </Card>
</CardGroup>

<Note>
  Check your Node.js version with `node --version`. If you need to manage multiple Node.js versions, consider using [nvm](https://github.com/nvm-sh/nvm).
</Note>

## Quick Install (Recommended)

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

<CodeGroup>
  ```bash Linux / macOS theme={null}
  curl -fsSL https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/install-qwen.sh | bash
  ```

  ```cmd Windows (Administrator) theme={null}
  curl -fsSL -o %TEMP%\install-qwen.bat https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/install-qwen.bat && %TEMP%\install-qwen.bat
  ```
</CodeGroup>

<Warning>
  **Windows users**: Run the command prompt as Administrator to ensure proper installation.
</Warning>

### After Installation

Restart your terminal to ensure environment variables take effect:

```bash theme={null}
# 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:

```bash theme={null}
npm install -g @qwen-code/qwen-code@latest
```

Verify the installation:

```bash theme={null}
qwen --version
```

<Note>
  The global installation makes the `qwen` command available system-wide.
</Note>

### Homebrew (macOS, Linux)

If you use Homebrew package manager:

```bash theme={null}
brew install qwen-code
```

Verify the installation:

```bash theme={null}
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.

<CodeGroup>
  ```bash NPM theme={null}
  npm update -g @qwen-code/qwen-code
  ```

  ```bash Homebrew theme={null}
  brew upgrade qwen-code
  ```

  ```bash Install Script theme={null}
  # Re-run the install script
  curl -fsSL https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/install-qwen.sh | bash
  ```
</CodeGroup>

<Tip>
  Qwen Code automatically checks for updates when you run it. You'll see a notification if a new version is available.
</Tip>

## Installation Verification

After installation, verify everything is working correctly:

<Steps>
  <Step title="Check version">
    ```bash theme={null}
    qwen --version
    ```

    You should see output like: `@qwen-code/qwen-code 0.12.1`
  </Step>

  <Step title="Test help command">
    ```bash theme={null}
    qwen --help
    ```

    This displays all available CLI options and commands.
  </Step>

  <Step title="Launch interactive mode">
    ```bash theme={null}
    qwen
    ```

    This starts the interactive terminal UI. Press `Ctrl+C` or type `/exit` to quit.
  </Step>
</Steps>

## Development Installation

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

<Steps>
  <Step title="Clone the repository">
    ```bash theme={null}
    git clone https://github.com/QwenLM/qwen-code.git
    cd qwen-code
    ```
  </Step>

  <Step title="Install dependencies">
    ```bash theme={null}
    npm install
    ```

    This installs all packages in the monorepo workspace.
  </Step>

  <Step title="Build the project">
    ```bash theme={null}
    npm run build
    ```

    This compiles TypeScript and bundles all packages.
  </Step>

  <Step title="Run from source">
    ```bash theme={null}
    npm start
    ```

    Or for development mode with hot reload:

    ```bash theme={null}
    npm run dev
    ```
  </Step>
</Steps>

<Note>
  For development, use Node.js version \~20.19.0 with [nvm](https://github.com/nvm-sh/nvm) for best compatibility.
</Note>

## Troubleshooting

### Common Issues

<AccordionGroup>
  <Accordion title="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:
       ```bash theme={null}
       npm config get prefix
       ```
       The bin directory should be in your system PATH.
    3. For npm installations, try:
       ```bash theme={null}
       npm install -g @qwen-code/qwen-code --force
       ```
  </Accordion>

  <Accordion title="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:
       ```bash theme={null}
       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)
  </Accordion>

  <Accordion title="Node.js version mismatch">
    **Issue**: Error about unsupported Node.js version.

    **Solutions**:

    1. Check your Node.js version:
       ```bash theme={null}
       node --version
       ```
    2. Update to Node.js 20 or later from [nodejs.org](https://nodejs.org/)
    3. Or use nvm to install the correct version:
       ```bash theme={null}
       nvm install 20
       nvm use 20
       ```
  </Accordion>

  <Accordion title="Windows installation issues">
    **Issue**: Installation fails on Windows.

    **Solutions**:

    1. Run Command Prompt or PowerShell as Administrator
    2. Ensure Windows Build Tools are installed:
       ```cmd theme={null}
       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
  </Accordion>
</AccordionGroup>

### Getting Help

If you continue to experience issues:

<CardGroup cols={2}>
  <Card title="GitHub Issues" icon="github" href="https://github.com/QwenLM/qwen-code/issues">
    Search existing issues or create a new one
  </Card>

  <Card title="Discord Community" icon="discord" href="https://discord.gg/ycKBjdNd">
    Ask for help in our community Discord
  </Card>
</CardGroup>

## Uninstallation

If you need to remove Qwen Code:

<CodeGroup>
  ```bash NPM theme={null}
  npm uninstall -g @qwen-code/qwen-code
  ```

  ```bash Homebrew theme={null}
  brew uninstall qwen-code
  ```
</CodeGroup>

To also remove configuration files:

```bash theme={null}
rm -rf ~/.qwen
```

<Warning>
  Removing `~/.qwen` deletes all your settings, authentication tokens, and session history.
</Warning>

## Next Steps

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

<Card title="Configure Authentication" icon="key" href="/authentication">
  Set up Qwen OAuth or API key authentication →
</Card>