qwen-code/scripts/installation/INSTALLATION_GUIDE.md

Installation Guide for Qwen Code with Source Tracking

This guide describes how to install Node.js and Qwen Code with source information tracking.

Overview

The installation scripts automate the process of installing Node.js (if not present or below version 20) and Qwen Code, while capturing and storing the installation source information for analytics and tracking purposes.

Installation Scripts

We provide platform-specific installation scripts:

• Linux/macOS: install-qwen-with-source.sh
• Windows: install-qwen-with-source.bat

Linux/macOS Installation

Script: install-qwen-with-source.sh

Features:

• Checks for existing Node.js installation and version
• Installs Node.js 20+ if needed using NVM
• Installs Qwen Code globally with source information
• Stores the source information in ~/.qwen/source.json

Usage:

# Install with a specific source
sh install-qwen-with-source.sh --source github

# Install with internal source
sh install-qwen-with-source.sh -s internal

# Show help
sh install-qwen-with-source.sh --help

Supported Source Values:

• github - Installed from GitHub repository
• npm - Installed from npm registry
• internal - Internal installation
• local-build - Local build installation

How it Works:

1. The script accepts a --source parameter to specify where Qwen Code is being installed from
2. It installs Node.js if needed
3. It installs Qwen Code globally
4. It creates ~/.qwen/source.json with the specified source information

Important Notes:

⚠️ After installation, you need to restart your terminal or run:

source ~/.bashrc  # For bash users
# or
source ~/.zshrc   # For zsh users

This is required to load the newly installed Node.js and Qwen Code into your PATH.

Prerequisites:

• curl (for NVM installation and script download)
• bash-compatible shell

Windows Installation

Script: install-qwen-with-source.bat

Features:

• Checks for existing Node.js installation and version (requires version 18+)
• Automatically downloads and installs Node.js 24 LTS if not present or version is too low
• Installs Qwen Code globally with source information
• Stores the source information in %USERPROFILE%\.qwen\source.json

Prerequisites:

• PowerShell (Administrator): The script must be run in PowerShell with Administrator privileges
• Internet connection for downloading Node.js and Qwen Code

Usage:

⚠️ Important: You must run PowerShell as Administrator to install Node.js and global npm packages.

Step 1: Open PowerShell as Administrator

• Right-click on PowerShell and select "Run as Administrator"
• Or press Win + X and select "Windows PowerShell (Admin)"

Step 2: Navigate to the script directory and run:

# Install with a specific source using --source parameter
./install-qwen-with-source.bat --source github

# Install with short parameter
./install-qwen-with-source.bat -s internal

# Use default source (unknown)
./install-qwen-with-source.bat

Supported Source Values:

• github - Installed from GitHub repository
• npm - Installed from npm registry
• internal - Internal installation
• local-build - Local build installation

How it Works:

1. The script accepts a --source or -s parameter to specify where Qwen Code is being installed from
2. It checks if Node.js is already installed and if the version is 18 or higher
3. If Node.js is not installed or version is too low, it automatically downloads and installs Node.js 24 LTS
4. It installs Qwen Code globally using npm
5. It creates %USERPROFILE%\.qwen\source.json with the specified source information

Why Administrator Privileges are Required:

• Installing Node.js requires writing to C:\Program Files\nodejs
• Installing global npm packages requires elevated permissions
• Modifying system PATH environment variables requires Administrator access

Installation Source Feature

Overview

This feature implements the ability to capture and store the installation source of the Qwen Code package. The source information is used for analytics and tracking purposes.

Storage Location

The installation source is stored in a separate file at:

• Unix/Linux/macOS: ~/.qwen/source.json
• Windows: %USERPROFILE%\.qwen\source.json (equivalent to C:\Users\{username}\.qwen\source.json)

File Format

The source.json file contains:

{
  "source": "github"
}

How the Source Information is Used

1. Telemetry Tracking: The source information is included in RUM (Real User Monitoring) telemetry logs
2. Analytics: Helps understand how users are discovering and installing Qwen Code
3. Distribution Analysis: Tracks which distribution channels are most popular

Technical Implementation

• The source information is stored as a separate JSON file
• The QwenLogger class reads this file during telemetry initialization
• The source is included in the app.channel field of the RUM payload
• The implementation gracefully handles missing files, unknown values, and parsing errors

Verification

After installation and restarting your terminal (or sourcing your shell configuration), you can verify the source information:

Linux/macOS:

cat ~/.qwen/source.json

Windows:

type %USERPROFILE%\.qwen\source.json

Manual Installation (Without Source Tracking)

If you prefer not to use the installation scripts or don't want source tracking:

Prerequisites

# Node.js 20+
curl -qL https://www.npmjs.com/install.sh | sh

NPM Installation

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

Homebrew (macOS, Linux)

brew install qwen-code

Troubleshooting

Script Execution Issues

Linux/macOS:

# Run with sh
sh install-qwen-with-source.sh --source github

Windows (PowerShell as Administrator):

# Run the script with --source parameter
./install-qwen-with-source.bat --source github

# Or with short parameter
./install-qwen-with-source.bat -s github

Node.js Installation Issues

Linux/macOS:

• Ensure NVM is installed: curl -o- https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/install_nvm.sh | bash
• Restart your terminal or run: source ~/.bashrc

Windows:

• Install NVM for Windows from: https://github.com/coreybutler/nvm-windows/releases
• After installation, run the script again

Permission Issues

You may need administrative privileges for global npm installation:

• Linux/macOS: Use sudo with npm
• Windows: Run PowerShell as Administrator (required for Node.js installation and global npm packages)

Notes

• The scripts require internet access to download Node.js and Qwen Code
• Administrative privileges may be required for global npm installation
• The installation source is stored locally and used for tracking purposes only
• If the source file is missing or invalid, the application continues to work normally