How to Install OpenCode: macOS, Linux & Windows

Steps

1. 01

   Choose an install method

   OpenCode ships three official install methods. The curl script and Homebrew are the quickest on macOS and Linux; the npm package (opencode-ai) works on every OS including Windows, so it is the most portable choice. Pick one — you do not need all three.

   # Portable (any OS, needs Node 18+):  npm i -g opencode-ai
   # Quickest on macOS/Linux:            curl -fsSL https://opencode.ai/install | bash
   # Homebrew (macOS/Linux):             brew install sst/tap/opencode

2. 02

   Install on macOS or Linux (curl or Homebrew)

   On macOS or Linux, the official install script is a single command. If you manage packages with Homebrew, the tap install is an equally good option and makes upgrades easy later.

   # Option 1 — official install script
   curl -fsSL https://opencode.ai/install | bash
   
   # Option 2 — Homebrew
   brew install sst/tap/opencode

3. 03

   Install on any OS with npm (incl. Windows)

   The npm package works on macOS, Linux, and Windows. This is the recommended path on Windows — run it in PowerShell or in a WSL shell. It requires Node.js 18 or later; if npm reports an engine error, upgrade Node first.

   npm i -g opencode-ai

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. With npm, pin the latest tag; with Homebrew, upgrade the formula. Re-check the version afterward.

   # npm
   npm i -g opencode-ai@latest
   
   # Homebrew
   brew upgrade opencode
   
   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: install or run behaves unexpectedly

On Windows, prefer the npm method in PowerShell, or run OpenCode inside WSL with the curl installer. If you hit native Windows-specific issues, confirm the current Windows guidance on opencode.ai — the cross-platform npm package is the most reliable path.