Alternative installation methods: npm, Homebrew, WinGet, and the WorkBuddy desktop version
The previous lesson covered the official recommended native installation path; this lesson, 8 minutes long, wraps up the installation series: it explains the three package-manager alternatives—npm, Homebrew, and WinGet—all at once, covering commands, trade-offs, and how to update; then it offers a replacement route for those who don't want to touch the command line at all: the WorkBuddy desktop version—download, install, and log in with WeChat QR code, all doable with mouse clicks.
One sentence to set the record straight: the npm package contains the same binary as the native installation, not a script running on Node; whichever way you install, the verification method is exactly the same. The difference lies only in "how you install and how you update"—think about what you want first, then pick a path. (Fact-checked 2026-11-04; commands and versions change over time, so defer to the official documentation.)
What you'll be able to do after this lesson
- Complete Claude Code npm installation with a single
npm install -gcommand, and upgrade with the correct command (avoiding thenpm update -gpitfall) - Install Claude Code with Homebrew / WinGet, and tell apart the
claude-codeandclaude-code@latestversion channels - Explain the update rules of the four installation methods: which auto-updates, which requires manual
brew upgrade/winget upgrade - Complete WorkBuddy download, installation (Windows / macOS), and WeChat QR code login without touching the command line
- Decide whether to stay on the native installation path from the previous lesson or switch to one of the alternative methods
Your current predicament
- The native installation command from the previous lesson didn't work, or you don't want to add "installation scripts of unknown origin" to your system—you'd rather manage software uniformly with a package manager you're familiar with
- You already have Node.js installed: you're used to
npm install -g, so can Claude Code be installed the same way? And how do you upgrade after installing? - You don't want to touch the terminal at all: the mere sight of a command line gives you a headache, and you just want to download a desktop app, click "Next" a few times, and start using it
When to use this approach
When you need to:
- Install and manage Claude Code with a package manager you're familiar with (npm / Homebrew / WinGet)
- Retry on another officially supported channel when the native installation fails
- A zero-command-line alternative route: desktop app + WeChat QR code, installed and logged in within minutes
And you don't want to:
- Try every method and end up with several overlapping copies of Claude Code installed on your system
- Ignore updates after installing and stay stuck on an old version with known issues
- Spend half a day learning the terminal and shell configuration just to install one AI coding tool
🎒 Preparation before starting
- Finish the previous lesson Installing Claude Code: if you've already installed it, you can skip the Claude Code parts of this lesson and go straight to the WorkBuddy desktop version in step 5
- The Claude Code parts: account and system requirements are the same as the previous lesson (Claude subscription or Console account; macOS 13.0+ / Windows 10 1809+ / Ubuntu 20.04+, at least 4 GB of RAM)
- For the npm route: Node.js 22 or later installed (run
node --versionin the terminal to check; ifnpm --versionprints something starting with12, see the version check in step 1) - For the Homebrew route: Homebrew already installed on your machine, and the
brewcommand runs in the terminal - For the WinGet route: the
wingetcommand runs in the terminal on Windows - For the WorkBuddy desktop version: Windows 10 or later (x64) or macOS 12 or later; WeChat on your phone, able to scan QR codes
Core idea
See all four alternative methods in one table—find your match first, then get started:
| Installation method | One command | Platform | How to update after install | Who it's for |
|---|---|---|---|---|
| npm (recommended in this lesson) | npm install -g @anthropic-ai/claude-code | macOS / Linux / Windows (requires Node.js 22+) | Auto-updates (provided you don't use sudo and the global directory is writable); manual upgrade with npm install -g @anthropic-ai/claude-code@latest | Those who already have the Node.js toolchain |
| Homebrew | brew install --cask claude-code | macOS | No auto-updates; manual upgrade with brew upgrade claude-code | Mac users accustomed to managing software with brew |
| WinGet | winget install Anthropic.ClaudeCode | Windows | No auto-updates; upgrade regularly with winget upgrade Anthropic.ClaudeCode | Accustomed to managing software with WinGet on Windows |
| WorkBuddy Desktop version | Download the installer from the official site workbuddy.cn | Windows 10+ (x64) / macOS 12+ (also available in the UOS and Kylin stores) | "Check for updates" inside the client | Don't want to touch the command line at all |
Before getting started, remember three key points:
- What npm installs is also the "native binary." The official docs state clearly: what the npm package pulls in via platform-specific optional dependencies (such as
@anthropic-ai/claude-code-darwin-arm64) is the same native binary as the one from the standalone installer; the installedclauderuntime does not invoke Node. Don't worry about "is the npm version a stripped-down version?"—it isn't. - Update rules are the focus of this lesson. The native installer updates automatically in the background; the npm method can also update automatically, but only if you didn't use
sudoduring installation and your npm global directory is writable; Homebrew, WinGet, and apt/dnf/apk all require manual upgrades by default. Not updating after installing = missing out on new features and security fixes. - WorkBuddy is not a "skin" of Claude Code. It is a separate product from Tencent: a desktop AI workbench that can write code, read projects, and develop websites and apps; you log in by scanning a WeChat QR code, and its account system is completely different from Claude Code. It solves the "zero command line" problem, not the "free access to Claude" problem—two different things, don't conflate them.
💡 Can't tell WorkBuddy apart from the Claude Code desktop version?
Claude Code also has an official desktop app (a GUI, no terminal needed), with official downloads for macOS, Windows, and Linux; WorkBuddy is a separate product from Tencent. Steps 5 and 6 of this lesson cover WorkBuddy; the various forms of Claude Code will be covered in Claude Code usage.
Follow along with me
First, match your toolchain: have Node.js → Step 1; Mac users → Step 2; Windows users → Step 3; want to touch neither → Steps 5 and 6. Step 4 (update rules) is recommended for everyone.
Step 1: Install Claude Code via npm with npm install -g
Why: npm is this lesson's recommended fallback channel: one command to install, it produces the same binary as the native installer, and it supports automatic updates—as long as you don't use sudo.
First, confirm your Node.js version (the npm package requires Node.js 22 or higher):
node --versionYou should see: v22 or a higher version number. If your Node version is on the older side, npm will print an EBADENGINE warning—the installation will still complete and claude will still run (because the package downloads a native binary that doesn't depend on your local Node), but it's still recommended to upgrade Node to 22+ before installing.
While you're at it, also check npm's own version:
npm --versionYou should see: a version number. If it starts with 12, don't force the install just yet—npm 12 has known installation issues; follow the official doc Fix an npm 12 install, or find your case in What to do if the install fails, then come back to install.
Then install (do not add sudo):
npm install -g @anthropic-ai/claude-codeYou should see: npm completes the installation normally with no errors. Open a new terminal window and run claude --version, which prints a version number + (Claude Code)—exactly the same verification method as in the previous lesson.
For future upgrades, use this (do not use npm update -g; see "Pitfall warnings" for the reason):
npm install -g @anthropic-ai/claude-code@latestPlatforms supported by the npm channel: darwin-arm64, darwin-x64, linux-x64, linux-arm64, linux-x64-musl, linux-arm64-musl, win32-x64, win32-arm64; your package manager needs to allow "optional dependencies." If you can't find the claude command after installing, find your case in What to do if the install fails.
- Quick check:
claude --versionprinted a version number with(Claude Code), and I did not usesudoduring installation
Step 2: Install Claude Code with Homebrew (for macOS users)
Why: If you're used to managing software with brew on your Mac, hand Claude Code over to brew for unified management—but note that after brew installs it, it will not update automatically; you have to upgrade manually.
Homebrew offers two casks; pick one first:
| cask | channel it tracks | characteristics |
|---|---|---|
claude-code | stable (stable version) | Usually about a week behind the latest release; skips versions with major regression issues |
claude-code@latest | latest Latest version | Follows new releases as soon as they're out |
Most people pick the stable version:
brew install --cask claude-codeYou should see: brew completes the installation process. Open a new terminal and run claude --version to verify.
For future upgrades (upgrade whichever cask you installed):
brew upgrade claude-code
# 装了 latest 通道的用:
brew upgrade claude-code@latest- Quick check: I know which cask I installed, and I remember that brew doesn't update automatically
Step 3: Install Claude Code with WinGet (for Windows users)
Why: If you manage software with WinGet on Windows, you can likewise install it with a single command—but likewise, after installation it will not update automatically; you need to upgrade manually on a regular basis.
Run this in PowerShell:
winget install Anthropic.ClaudeCodeYou should see: WinGet completes the download and installation process. Open a new terminal and run claude --version to verify.
For regular upgrades later:
winget upgrade Anthropic.ClaudeCodeNote: while Claude Code is running, Windows locks its executable file, and the upgrade may fail in that case—quit Claude Code first, then upgrade.
- Quick check:
claude --versionprinted a version number; I've memorized that the upgrade command iswinget upgrade
Step 4: Verify the installation and figure out the Claude Code update rules
Why: The verification method is the same for claude installed via any of these methods; but the update rules differ—the first thing to do after installing is figure out "who manages my installation, and how do I upgrade it."
Verify (open a new terminal):
claude --versionYou should see: a version number + (Claude Code), for example 2.1.211 (Claude Code).
To check the installation's health status, run a read-only diagnostic as well:
claude doctorYou should see: diagnostic information about the installation and configuration—including the result of the most recent automatic update, with fix suggestions attached if there are issues.
Update rules reference table:
| How you installed it | Auto-updates? | Manual upgrade command |
|---|---|---|
| Native installation (previous lesson) | ✅ Updates automatically in the background | claude update (applies updates immediately) |
| npm | ✅ Can auto-update (provided the global directory is writable and you didn't use sudo) | npm install -g @anthropic-ai/claude-code@latest |
| Homebrew | ❌ Not automatic by default | brew upgrade claude-code (or claude-code@latest) |
| WinGet | ❌ Not automatic by default | winget upgrade Anthropic.ClaudeCode |
One easily confusing point: for installations managed by Homebrew / WinGet, running claude update will report Claude is up to date!—for these installations, updates go through the package manager; just upgrade with the corresponding command in the table above.
- Quick check: I can state who manages updates for my installation method, along with the corresponding manual upgrade command
Step 5: WorkBuddy download and installation—the zero-command-line route
Why: For those who don't want to touch the terminal at all, this route is entirely mouse-driven: download the installer from the official website → double-click to install → scan the QR code with WeChat to log in. WorkBuddy is a desktop AI workbench from Tencent that also covers development scenarios such as writing code, reading projects, and building websites and apps.
First, verify the system requirements:
| System | Requirements |
|---|---|
| Windows | Windows 10 and above, x64; Windows 7/8/8.1 not supported (ARM64 device support is subject to the current version's documentation) |
| macOS | macOS 12 (Monterey) and above |
| UnionTech UOS / Kylin | Search and install via the system app store / software store (UOS supports x86_64 and ARM64; Kylin desktop version V10) |
Systems that don't meet the requirements cannot launch WorkBuddy—upgrade your system first, then install.
Windows users
- Visit the WorkBuddy official website, click "Download Now", choose Windows, and download the installer
- Once the download finishes, double-click the installer to launch the setup wizard
- Check "I agree to this agreement", then click Next
- Choose the installation path (with the default path, you can just click Next)
- Confirm the Start Menu folder, then click Next
- It's recommended to check "Create desktop shortcut", then click Next
- Confirm the settings are correct and click Install; when it finishes, click Finish to exit the setup wizard
You should see: a WorkBuddy shortcut appears on the desktop, and double-clicking launches it.
macOS users
- Visit the WorkBuddy official website, click "Download Now", and choose the Mac version—M-series chips choose Mac ARM64, Intel chips choose Mac X64; if the website doesn't recognize your device, it offers the X64 version by default (it can run on M-series via Rosetta, with broader compatibility). If you don't know your chip, click the Apple icon in the top-left corner of the screen → "About This Mac" to check
- Allow the download in the browser popup and wait for the installer to finish downloading
- Double-click the downloaded
.dmgfile to open the installation window - Drag the WorkBuddy icon into the Applications folder—don't skip this step; see "Pitfall reminders" for the reason
- Wait for the copy to finish, then eject the mounted WorkBuddy disk image; if you no longer need it, you can delete the
.dmginstaller
You should see: WorkBuddy can be found in Launchpad (or via Command + 空格 search), and it launches from the "Applications" folder.
- Quick check: WorkBuddy launches from the "Applications" folder (on Windows, from the Start Menu / desktop shortcut), not directly from the installer
Step 6: Log in to WorkBuddy by scanning the WeChat QR code and confirm it can update
Why: Installing is only half the journey—only after logging in and confirming the update channel works can it be considered "usable".
- Launch WorkBuddy and click the login button
- The browser automatically opens the official login page; in the popup, check the User Service Agreement and Privacy Policy
- Scan the QR code with WeChat to complete login; phone number, email, SSO, and other methods are also supported, all completed on the current page with no redirects
- After the page shows the login succeeded, return to the client
You should see: the client enters the main interface, and you can "create a new task".
Confirm the update channel: click your avatar in the bottom-left corner → "Check for updates". If you're already on the latest version, no action is needed; when a new version is available, the system will download and complete the upgrade automatically.
(On Mac, if you're told it can't auto-update, it means WorkBuddy was run directly from the .dmg disk image—click "Move to Applications" as prompted, or manually drag it into the "Applications" folder, then relaunch it from there.)
Costs in one sentence: WorkBuddy has a free trial edition (500 credits/month); for paid tiers and credit rules, see pricing comparison and WorkBuddy usage.
- Quick check: WeChat QR-code login succeeded and the client opens normally; "Check for updates" responds normally
Checkpoint ✅
- I installed Claude Code via one of npm / Homebrew / WinGet, and
claude --versionprints the version number +(Claude Code) - npm method: I didn't use
sudo npm install -g; for upgrades I usenpm install -g @anthropic-ai/claude-code@latest, notnpm update -g - Homebrew / WinGet method: I know it doesn't auto-update after installation, and I've memorized the
brew upgrade/winget upgradeupgrade commands - WorkBuddy desktop edition installed and logged in successfully via WeChat QR code; on Mac, it launches from the "Applications" folder
- I can state who manages updates for my current installation method, and when errors occur I know to look up What to do if installation fails
Pitfall reminders
❌ Installing with sudo npm install -g
The official documentation explicitly warns: do not use sudo to install global packages—it causes permission problems and security risks; moreover, when Claude Code updates itself it runs npm without sudo, so an installation done with sudo cannot update automatically.
The correct approach: drop sudo and install directly. If you hit a permission error (the npm global directory is not writable), go to What to do if installation fails and handle it accordingly—don't force your way through with sudo.
❌ Upgrading Claude Code with npm update -g
npm update -g follows the semver version range from the original installation, so it may not upgrade to the latest version.
The correct approach:
# ❌ 可能升不到最新
npm update -g
# ✅ 明确指定装最新版
npm install -g @anthropic-ai/claude-code@latest❌ Assuming Homebrew / WinGet will auto-update after installation
It won't. Both of these methods require manual upgrades by default (brew upgrade claude-code / winget upgrade Anthropic.ClaudeCode). Two additional reminders:
- Don't panic if an upgrade fails: Claude Code may notify you of an update before the new version is available in the package manager—the official documentation calls this a known issue, so just try again later. When upgrading with WinGet, if Claude Code is running, Windows locking the executable can also cause failure—quit it first, then upgrade.
- brew keeps old versions taking up disk space: after a Homebrew upgrade, the old version remains on disk; the official recommendation is to run
brew cleanupperiodically to reclaim space.
❌ Double-clicking .dmg on Mac to run WorkBuddy directly
Running directly from the disk image means WorkBuddy runs on a read-only image, so it cannot update automatically afterward.
The correct approach: drag WorkBuddy into the "Applications" folder first, then launch it. If you've already fallen into this trap, there's no need to reinstall—click the "Move to Applications" button in the update prompt, or drag it in manually, then relaunch it from "Applications".
Advanced tips (optional)
Let Claude Code run the upgrade command for you. Homebrew / WinGet users can set this in settings.json:
{
"env": {
"CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE": "1"
}
}Afterward, when Claude Code detects a new version, it will run the corresponding upgrade command for you in the background—touching only the Claude Code package itself, without affecting your other installed software. On WinGet, if Claude Code is running during the upgrade, it will instead display a manual command for you to copy and run.
Linux users: apt / dnf / apk. Debian/Ubuntu, Fedora/RHEL, and Alpine can install Claude Code from Anthropic's signed repositories, likewise with stable (about a week behind) and latest dual channels; upgrades go through the system package manager (e.g., sudo apt update && sudo apt upgrade claude-code)—see the official documentation Install with Linux package managers for the full commands.
Users of domestic (Chinese) operating systems. WorkBuddy is distributed through the system store on UnionTech UOS and Kylin: on UOS, open the built-in App Store; on Kylin, open the Software Store in the taskbar; search for WorkBuddy and click install—updates are also done in the store.
WorkBuddy interface language. To switch languages: avatar in the bottom-left corner → Settings → General → Language.
Lesson summary
✅ Claude Code npm install = npm install -g @anthropic-ai/claude-code (no sudo), upgrade with npm install -g @anthropic-ai/claude-code@latest; the npm package also wraps the native binary, so the installed claude does not depend on Node at runtime.
✅ Homebrew has two casks: claude-code (stable, about a week behind) / claude-code@latest (latest); WinGet is a single winget install Anthropic.ClaudeCode. Neither will update automatically after installation; you need to manually run brew upgrade / winget upgrade.
✅ Update rules in three tiers: native installs update automatically in the background; npm can auto-update (provided you don't use sudo and the global directory is writable); Homebrew / WinGet / apt / dnf / apk are manual by default. claude doctor can check installation health and the result of the most recent update.
✅ WorkBuddy desktop edition = the zero-command-line route: download from the official site workbuddy.cn → double-click to install on Windows / drag into "Applications" on Mac → log in by scanning the WeChat QR code; updates are under "avatar in the bottom-left corner → Check for updates" in the client.
✅ Choosing in one sentence: have a Node toolchain → npm; Mac users → Homebrew; Windows users → WinGet; want nothing to do with the command line → WorkBuddy; don't want any hassle → go back to the native installation main path from the previous lesson.
Key commands recap:
| Command | Purpose | Applies to |
|---|---|---|
npm install -g @anthropic-ai/claude-code | Install Claude Code via npm | Node.js 22+, all platforms |
npm install -g @anthropic-ai/claude-code@latest | Upgrade to the latest version via npm | Users who installed via npm |
brew install --cask claude-code | Install via Homebrew (stable channel) | macOS |
brew upgrade claude-code | Manual upgrade via Homebrew | Users who installed via Homebrew |
winget install Anthropic.ClaudeCode | Install via WinGet | Windows |
winget upgrade Anthropic.ClaudeCode | Manual upgrade via WinGet | Users who installed via WinGet |
claude --version / claude doctor | Verify installation / read-only diagnostics | All platforms |
Next lesson preview
With more ways to install come more shapes of errors. Next lesson: What to do if installation fails: quick-start troubleshooting, a 60-second lookup.
You will learn:
- The 60-second fixes for
command not found/'claude' is not recognized(usually PATH isn't configured correctly) - How to handle npm permission errors and npm 12 installation issues
- What to check first when it installs but errors on startup, or login gets stuck
- Which errors mean you should retry with a different installation channel