OpenCode Install on Windows, macOS & Linux

Steps

1. 01

   Choose an install method

   OpenCode has more install paths than most guides list. On macOS and Linux the curl script or Homebrew are quickest. On Windows you have four native options (Chocolatey, Scoop, npm, Mise) plus Docker and a plain binary — and the official docs recommend running OpenCode inside WSL for the best experience. Pick one path; you do not need several.

   # macOS / Linux, quickest:   curl -fsSL https://opencode.ai/install | bash
   # macOS / Linux, Homebrew:   brew install anomalyco/tap/opencode
   # Windows, native:           choco install opencode   (or: scoop install opencode)
   # Any OS, needs Node 18+:    npm install -g opencode-ai
   # Windows, best experience:  run the curl script inside WSL

2. 02

   Install on macOS or Linux (curl, Homebrew or your distro)

   On macOS or Linux, the official install script is a single command. If you manage packages with Homebrew, use the project's own tap — the docs note that the official Homebrew formula (brew install opencode) is maintained by the Homebrew team and updates less often. Arch Linux has packages in both the main repo and the AUR.

   # Option 1 — official install script
   curl -fsSL https://opencode.ai/install | bash
   
   # Option 2 — Homebrew (project tap, freshest)
   brew install anomalyco/tap/opencode
   
   # Option 3 — Arch Linux
   sudo pacman -S opencode      # stable
   paru -S opencode-bin         # latest, from the AUR

3. 03

   OpenCode install on Windows: WSL, Chocolatey, Scoop, npm, Mise or Docker

   The official docs recommend WSL first — it gives better performance and full feature compatibility, and lets you use the same curl script as Linux. If you would rather stay on native Windows, Chocolatey and Scoop both carry OpenCode, npm works anywhere Node 18+ is installed, and Mise or Docker cover the remaining cases. One caveat worth knowing before you start: installing OpenCode on Windows via Bun is still in progress, so do not reach for bun install here. If a native install misbehaves, the three Windows-specific failure modes in Troubleshooting below cover what almost always goes wrong.

   # Recommended — inside WSL, same as Linux
   wsl
   curl -fsSL https://opencode.ai/install | bash
   
   # Native Windows — Chocolatey
   choco install opencode
   
   # Native Windows — Scoop
   scoop install opencode
   
   # Native Windows — npm (needs Node 18+)
   npm install -g opencode-ai
   
   # Native Windows — Mise
   mise use -g github:anomalyco/opencode
   
   # No install at all — Docker
   docker run -it --rm ghcr.io/anomalyco/opencode
   
   # Or grab a binary straight from the GitHub Releases page

4. 04

   Verify the install

   Confirm the binary is on your PATH by printing the version. You should see 1.17.8 or later. If the command is not found, jump to the PATH fix in Troubleshooting.

   opencode --version

5. 05

   Authenticate a model provider

   OpenCode is model-agnostic: you bring your own provider key, stored locally. Run the login command and follow the prompts to add your first provider (Anthropic, OpenAI, Google, and 75+ more). GitHub Copilot and ChatGPT can be connected via OAuth so usage rolls into an existing subscription.

   opencode auth login
   # alias:
   opencode providers login

6. 06

   Run OpenCode for the first time

   Launch the interactive TUI to start a session, run a single headless task for scripting/CI, or start server mode. The same agent core backs all three.

   # Interactive TUI
   opencode
   
   # One-shot headless task
   opencode run "explain what this repo does"
   
   # Server mode
   opencode serve

7. 07

   Update or reinstall later

   To upgrade, re-run your install method rather than trusting a built-in updater. On Windows in particular, do not rely on opencode upgrade: it reports success but leaves the old binary in place, because the install script tries to move a new file over an executable that Windows has locked while it runs (issue #37055). Whatever path you used, re-check the version afterward — that is the only way to know the upgrade actually landed.

   # npm
   npm install -g opencode-ai@latest
   
   # Homebrew
   brew upgrade opencode
   
   # Windows — re-run the package manager, not `opencode upgrade`
   choco upgrade opencode
   scoop update opencode
   
   # Always confirm it actually changed
   opencode --version

Troubleshooting

opencode: command not found after npm install

The npm global bin directory is not on your PATH. Run npm prefix -g to find the global prefix (the bin directory is that path + /bin), then add it to your shell profile: export PATH="$(npm prefix -g)/bin:$PATH" in ~/.zshrc or ~/.bashrc, and reload with source ~/.zshrc. Alternatively use the curl installer or Homebrew, which place the binary in a standard location.

npm ERR! engine: requires node >=18 (or a Node version error)

The npm method needs Node.js 18 or later. Check with node --version. If it is older, upgrade via nvm (nvm install --lts && nvm use --lts) or download from nodejs.org, then re-run npm i -g opencode-ai.

OpenCode launches but errors that no model/provider is configured

You have not authenticated a provider yet. Run opencode auth login and add at least one provider (with its API key) or connect GitHub Copilot / ChatGPT via OAuth. Keys are stored locally; the agent needs a model before it can act.

The curl install script is blocked (corporate proxy, no network access)

Use the npm method instead (npm i -g opencode-ai), which goes through your existing npm registry/proxy config. If npm is also proxied, set npm's proxy (npm config set proxy / https-proxy) or download per the instructions on opencode.ai.

Windows: "The specified executable is not a valid application for this OS platform" after npm install -g opencode-ai

This is the known corrupted-executable bug (issues #37566, #36737, #27963). npm's postinstall step is what downloads the real binary; when it is blocked, npm leaves behind a 479-byte placeholder opencode.exe and every terminal (cmd, pwsh, Windows Terminal) fails the same way. Diagnose it by size — run: Get-Item "$(npm prefix -g)\node_modules\opencode-ai\bin\opencode.exe" | Select-Object Name, Length — a real binary is megabytes, 479 bytes means the placeholder. Fix by letting the postinstall run (make sure npm scripts are not disabled by ignore-scripts=true in your .npmrc or by a corporate policy) and reinstalling, or sidestep npm entirely with choco install opencode, scoop install opencode, or the curl script inside WSL.

Windows: git, node or other tools are "not found" inside OpenCode but work fine in PowerShell

OpenCode's TUI is not inheriting your shell's PATH — the sub-shell it spawns sees only C:\Windows\System32 (issue #37125, and the related PowerShell 5.1-vs-7 mismatch in #17372). This is a regression: versions 1.17.19 through 1.18.3 are affected, 1.17.18 is not. Until a fix ships, either pin to 1.17.18 (npm install -g opencode-ai@1.17.18), or run OpenCode inside WSL where the Linux PATH is inherited normally. Note this is a runtime bug, not an install problem — reinstalling will not change it.

Windows: `opencode upgrade` says "Upgrade complete" but the version never changes

Silent upgrade failure (issue #37055). The upgrade path runs the bash install script, which downloads the new binary and moves it over the running executable — but Windows locks a running .exe, so the move fails and the script still reports success. Upgrade through whichever package manager you installed with instead (choco upgrade opencode, scoop update opencode, or npm install -g opencode-ai@latest), then confirm with opencode --version before assuming it worked.

Windows: the VS Code extension fails with spawn opencode ENOENT

The extension cannot find the opencode binary on PATH (issue #38376). Confirm the CLI resolves in a normal terminal first with: Get-Command opencode. If it does not, your install did not put the binary on PATH — reinstall via Chocolatey or Scoop, which handle PATH registration, rather than a manual binary drop. If the CLI does resolve but VS Code still cannot see it, restart VS Code so it picks up the updated environment; VS Code caches PATH from the process that launched it.