Install OpenCode: macOS, Windows & Linux

Choose one installation method, verify the executable, then connect a provider. This guide is maintained independently by OpenCode Tutorial; installation commands were checked against the official installation guide on October 2, 2026.

Choose an installation method

Your environment	Start here
macOS with Homebrew	Official Homebrew tap
macOS or Linux without Node.js	Official install script
Existing Node.js environment	npm package, including native Windows
Windows with Linux development tools	WSL, then the Linux instructions

Avoid installing with several package managers at once. Multiple executables can make an upgrade appear to have no effect because your terminal finds an older copy first.

npm

If Node.js and npm are already available, run:

bash

npm install -g opencode-ai
opencode --version

The package name is opencode-ai; the command you run afterward is opencode.

macOS with Homebrew

Use the official tap for the current release:

bash

brew install anomalyco/tap/opencode
opencode --version

macOS or Linux with the install script

bash

curl -fsSL https://opencode.ai/install | bash

Open a new terminal after installation, then run opencode --version. Follow the installer’s PATH instructions if the command is unavailable. The old /install.sh URL is not the command shown in the current guide.

Windows and WSL

For a Linux development environment on Windows, set up WSL using the Microsoft WSL instructions. Run the Linux installation command inside the WSL terminal and open your project from that environment.

For native Windows, the npm method above is also listed in the official installation guide. Consult the OpenCode Windows guide for platform-specific requirements. Installing in PowerShell does not automatically install a second copy inside WSL.

Start your first project

Change into a real project directory and launch OpenCode:

bash

cd your-project
opencode

Inside the terminal interface:

Run /connect and select your model provider. Complete its authentication flow.
Run /init to create project instructions in AGENTS.md; review the generated file.
Ask a small question about the project before requesting a change.

Continue with Plan vs Build mode to choose how OpenCode handles a task. For language diagnostics, follow OpenCode LSP setup.

Fix “zsh: command not found: opencode”

Start by distinguishing a failed install from a PATH problem:

bash

command -v opencode
npm list -g opencode-ai --depth=0
npm prefix -g

The npm commands apply to an npm installation. On macOS and Linux, npm normally places global executables in the bin directory beneath the printed prefix. If the package is installed but command -v finds nothing, make that directory available in your shell’s PATH, then open a new terminal. Use the actual prefix on your machine rather than copying someone else’s path.

For a Homebrew installation, check brew list opencode and follow Homebrew’s shellenv setup instructions. For a script installation, use the directory reported by its installer. In WSL, repeat the check inside WSL rather than checking only the Windows shell.

If more than one copy exists, this command shows which one your shell will use first:

bash

type -a opencode

Upgrade an existing installation

Check your installed version and use the matching installation method to update it:

bash

opencode --version
opencode upgrade

If an npm-managed install needs updating through npm, use npm install -g opencode-ai@latest. For the official Homebrew tap, use brew upgrade anomalyco/tap/opencode. Check the version again in a new terminal.

If a service reports that a newer OpenCode version is required, compare its required version with opencode --version and check for duplicate executables before changing credentials. The CLI upgrade reference describes available options.

Where configuration belongs

Current OpenCode uses JSON or JSONC configuration. A project can use opencode.json; the global configuration lives at ~/.config/opencode/opencode.json. See configuration examples before adding settings.

Earlier versions of this tutorial referenced a Go installation from the old repository and config.yaml. Those instructions have been removed. Use the current package or official installer for a new installation.