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:

https://opencode.ai/v2/docs

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