OpenCode: download and install on Linux, macOS, Windows and Docker
Introduction
This page covers installation only. Using OpenCode daily — models,
agents, skills, workflows — is the next article:
OpenCode coding agent.
Pick one method below, verify with
opencode --version, then continue to
Connect a model.
V2 only: remove a package-managed V1 install first, the V2 curl
installer replaces the V1 binary. Supported V1 config files keep
working, only plugins and the server API break intentionally.
Install script
Recommended for Linux, macOS and WSL2:
curl -fsSL https://opencode.ai/v2/install | bash
Restart the terminal after install so the PATH update applies, then verify as in Verify, upgrade, service.
npm, Bun, pnpm, yarn
Any OS with Node.js, V2 package name:
npm install -g @opencode/cli
bun install -g --trust @opencode/cli
pnpm add -g --allow-build=@opencode/cli @opencode/cli
yarn global add @opencode/cli
Bun and pnpm need the explicit build flag for the postinstall script that selects the native binary. If the shell reports command not found, the global bin dir is not on PATH — see Troubleshooting.
Homebrew
macOS and Linux, V2 tap:
brew install anomalyco/tap/opencode-v2
Arch Linux
AUR, V2 beta package:
paru -S opencode-beta
Docker without install
Versioned tags, no install at all:
docker run -it --rm ghcr.io/anomalyco/opencode:2.0.0
Replace the tag with the release you need. Mount the project dir for real work, otherwise the agent sees only the container filesystem.
Desktop app and standalone binary
Desktop builds for macOS, Windows and Linux (deb, rpm, AppImage) plus standalone CLI zips and tarballs per platform are linked from the V2 docs front page:
Windows notes
Windows package managers are not supported for V2 — use npm or the standalone zip from the docs page above. WSL2 follows the Linux script path. The desktop app is the smoothest native Windows option.
Verify, upgrade, service
opencode --version
opencode upgrade
opencode service status
Upgrade to a pinned version with a chosen package manager:
opencode upgrade 2.0.21 --method bun
Troubleshooting
- Command not found after install: restart the terminal (PATH update) or rerun the installer; with npm check that the global bin dir is on PATH.
- Wrong version runs: a V1 binary shadows V2 — remove the package-managed V1 install, then reinstall V2 and re-check opencode --version.
- Service stuck after upgrade: opencode service restart then opencode service status; automatic install does not restart a running server.
- Docker sees no files: you forgot the volume mount — the agent works on the container filesystem unless the project dir is mounted in.
Next step: OpenCode coding agent — Connect a model first.
Article author: Arthur Isaev