scripts/installation/INSTALLATION_GUIDE.md
This guide describes the source-tracking installation scripts for Qwen Code. The scripts prefer standalone release archives and can fall back to npm when a standalone archive is not available.
The installers are intentionally lightweight:
qwen shim is discoverable.qwen automatically after installation.~/.qwen/source.json or
%USERPROFILE%\.qwen\source.json when --source is provided.Standalone archives include a private Node.js runtime, so users do not need a
local Node.js installation on the standalone path. Node.js 22 or newer and npm
are only required when the installer falls back to npm or when
--method npm is used.
install-qwen-standalone.shinstall-qwen-standalone.ps1uninstall-qwen-standalone.shuninstall-qwen-standalone.ps1GitHub releases publish these standalone archives:
qwen-code-darwin-arm64.tar.gzqwen-code-darwin-x64.tar.gzqwen-code-linux-arm64.tar.gzqwen-code-linux-x64.tar.gzqwen-code-win-x64.zipSHA256SUMSThe new standalone-first installer scripts (install-qwen-standalone.sh,
install-qwen-standalone.ps1) are not republished per release. They are served
from a hosted installation endpoint and accept --version to pin a specific
standalone release. The standalone suffix intentionally avoids overwriting the
existing production install-qwen.sh / install-qwen.bat OSS objects during
the staged rollout.
Public installation documentation intentionally continues to use the existing production installer in this PR. Update README and other public quick-install instructions in a follow-up after the standalone-suffixed hosted installers and release archive sync have been validated in production.
Hosted installer assets are staged separately from GitHub Release archives:
install-qwen-standalone.sh is the Linux/macOS hosted entrypoint.install-qwen-standalone.ps1 is the Windows hosted entrypoint for irm | iex.install-qwen-standalone.bat is the Windows installer implementation used by
install-qwen-standalone.ps1 and can also be downloaded and run directly.uninstall-qwen-standalone.sh removes Linux/macOS standalone installs.uninstall-qwen-standalone.ps1 removes Windows standalone installs.The global standalone-suffixed OSS entrypoints are maintained under
installation/install-qwen-standalone.sh,
installation/install-qwen-standalone.ps1,
installation/install-qwen-standalone.bat,
installation/uninstall-qwen-standalone.sh, and
installation/uninstall-qwen-standalone.ps1.
Build them with:
npm run package:hosted-installation -- --out-dir dist/installation
The staged install-qwen-standalone.sh, install-qwen-standalone.ps1,
install-qwen-standalone.bat, uninstall-qwen-standalone.sh, and
uninstall-qwen-standalone.ps1 files map to the standalone-suffixed hosted URLs
shown above. The staging command also writes SHA256SUMS for upload
verification. During a non-dry-run stable release, the publish workflow uploads
a byte-for-byte snapshot to installation/vX.Y.Z/ for audit and rollback, and
also refreshes the global installation/ entrypoint objects so curl | bash
links keep resolving without a version segment. The versioned snapshot lets you
roll back by repointing the global objects to a previous tag if a regression is
caught after publish. The hosted
installers intentionally default to latest; on Aliyun OSS this means reading
releases/qwen-code/latest/VERSION first, then downloading the matching
versioned release directory. Use --version or QWEN_INSTALL_VERSION to pin a
standalone release directly.
Configure the production-release GitHub environment with these required
secrets before enabling OSS sync:
ALIYUN_OSS_ACCESS_KEY_IDALIYUN_OSS_ACCESS_KEY_SECRETThe workflow defaults to the production OSS bucket and Hangzhou endpoint. Set these GitHub Actions variables only when the bucket, endpoint, or public base URL changes:
ALIYUN_OSS_BUCKET (default: qwen-code-assets)ALIYUN_OSS_ENDPOINT (default: https://oss-cn-hangzhou.aliyuncs.com)ALIYUN_OSS_PUBLIC_BASE_URL (default:
https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com)Archive layout:
qwen-code/
bin/qwen
bin/qwen.cmd
lib/cli.js
node/
package.json
README.md
LICENSE
manifest.json
The default method is detect:
SHA256SUMS.You can force a method:
bash install-qwen-standalone.sh --method standalone
bash install-qwen-standalone.sh --method npm
install-qwen-standalone.bat --method standalone
install-qwen-standalone.bat --method npm
The standalone archives bundle Qwen Code and a private Node.js runtime. They do
not currently install npm optional native modules such as node-pty and
@teddyzhu/clipboard. Qwen Code is designed to degrade when these optional
modules are absent, but terminal pty behavior and clipboard image support may
not be identical to an npm installation.
Use --method npm if you specifically need npm to resolve optional native
modules for the current machine.
# Default: standalone archive with npm fallback
bash install-qwen-standalone.sh
# Record a source value
bash install-qwen-standalone.sh --source github
# Use npm explicitly
bash install-qwen-standalone.sh --method npm --registry https://registry.npmjs.org
# Use the Aliyun standalone mirror
bash install-qwen-standalone.sh --mirror aliyun
# Install an offline archive
# SHA256SUMS must be in the same directory.
bash install-qwen-standalone.sh --archive ./qwen-code-linux-x64.tar.gz
Standalone installs to:
~/.local/lib/qwen-code~/.local/bin/qwenOverride with QWEN_INSTALL_ROOT, QWEN_INSTALL_LIB_PARENT,
QWEN_INSTALL_LIB_DIR, or QWEN_INSTALL_BIN_DIR when needed.
Uninstall a standalone Linux/macOS install:
curl -fsSL https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/uninstall-qwen-standalone.sh | bash
The uninstaller removes only the standalone runtime, generated qwen wrapper,
and installer-managed shell PATH block. It preserves ~/.qwen by default. Set
QWEN_UNINSTALL_PURGE=1 to remove ~/.qwen/source.json; other config and auth
files are still preserved.
REM Default: standalone archive with npm fallback
install-qwen-standalone.bat
REM Record a source value
install-qwen-standalone.bat --source github
REM Use npm explicitly
install-qwen-standalone.bat --method npm --registry https://registry.npmjs.org
REM Use the Aliyun standalone mirror
install-qwen-standalone.bat --mirror aliyun
REM Install an offline archive
REM SHA256SUMS must be in the same directory.
install-qwen-standalone.bat --archive qwen-code-win-x64.zip
Standalone installs to:
%LOCALAPPDATA%\qwen-code\qwen-code%LOCALAPPDATA%\qwen-code\bin\qwen.cmdOverride with QWEN_INSTALL_ROOT, QWEN_INSTALL_LIB_DIR, or
QWEN_INSTALL_BIN_DIR when needed.
Restart the terminal if qwen is not immediately available on PATH.
Uninstall a standalone Windows install:
powershell -ExecutionPolicy Bypass -c "irm https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/uninstall-qwen-standalone.ps1 | iex"
The uninstaller removes only the standalone runtime, generated qwen.cmd
wrapper, user PATH entry, and the current-session cmd.exe shim created by the
hosted PowerShell installer. It preserves %USERPROFILE%\.qwen by default. Set
QWEN_UNINSTALL_PURGE=1 to remove %USERPROFILE%\.qwen\source.json; other
config and auth files are still preserved.
Options:
--method detect|standalone|npm--mirror github|aliyun--base-url URL--archive PATH--version VERSION--registry REGISTRY--source SOURCEEnvironment variables:
QWEN_INSTALL_METHODQWEN_INSTALL_MIRRORQWEN_INSTALL_BASE_URLQWEN_INSTALL_ARCHIVEQWEN_INSTALL_VERSIONQWEN_NPM_REGISTRYUse --base-url for private mirrors. The URL must contain
qwen-code-<target> archives and SHA256SUMS in the same directory. Custom
base URLs must use https://.
For Aliyun OSS/CDN, release publishing uploads byte-identical artifacts to the
versioned directory, for example releases/qwen-code/vX.Y.Z/. Stable releases
also update the small releases/qwen-code/latest/VERSION pointer used by the
default installer path. The installer reads that pointer and then downloads the
versioned archive plus the versioned SHA256SUMS; nightly and preview releases
do not update the pointer.
The source value may only contain letters, numbers, dot, underscore, and dash. Common values are:
githubnpminternallocal-buildWhen --source or -s is provided, the installer writes:
{
"source": "github"
}
Locations:
~/.qwen/source.json%USERPROFILE%\.qwen\source.jsonThe telemetry logger reads this file when available. Missing, invalid, or unreadable source files are ignored.
If source tracking is not needed and Node.js 22 or newer is already available:
npm install -g @qwen-code/qwen-code@latest
Homebrew users can also install Qwen Code with:
brew install qwen-code
In detect mode, the installer falls back to npm. In standalone mode, install
fails so that automation can detect the missing artifact.
This only blocks npm installation. Install or activate Node.js 22 or newer, then
rerun the installer with --method npm or let detect fall back again.
Install a Node.js distribution that includes npm, then rerun the installer.
The installers do not rewrite npm prefix settings. If global npm installation fails with a permission error, fix the npm global install location or use a user-owned Node.js installation, then rerun:
npm install -g @qwen-code/qwen-code@latest --registry https://registry.npmmirror.com
Restart the terminal first. For standalone installs, add the shim directory:
export PATH="$HOME/.local/bin:$PATH"
For npm installs, add npm's global binary directory. On Linux/macOS this is usually:
export PATH="$(npm prefix -g)/bin:$PATH"
On Windows standalone installs, add this directory to PATH:
%LOCALAPPDATA%\qwen-code\bin