How to install OpenCode on Mac, Windows and Linux

To install OpenCode, run curl -fsSL https://opencode.ai/install | bash on macOS, Linux or WSL, or npm install -g opencode-ai on any system with Node.js. Then cd into a project, run opencode and add a model with /connect. opencode.ai's home page and OpenCode's README now offer OpenCode 2, a new major version with its own install command; the docs at opencode.ai/docs, the GitHub releases and the Windows package managers still install OpenCode 1. This page covers both, as read on 20 October 2026.

Install OpenCode on macOS

The script downloads the build for your Mac from GitHub, picks the Intel build without AVX2 on an older Intel Mac, puts opencode in ~/.opencode/bin and adds that folder to your shell's rc file. Open a new terminal before you check. --no-modify-path leaves the rc file alone, and --version 1.18.34 installs an older release.

OpenCode recommends the tap over Homebrew's own formula. Plain brew install opencode is the core formula, which Homebrew builds from source: on 20 October it gave OpenCode 2.1.0, not OpenCode 1. Adding the tap does not change that; type the full name, anomalyco/tap/opencode.

Install OpenCode on Linux

On Linux the script also picks a musl build on Alpine and similar systems, and the build without AVX2 when /proc/cpuinfo does not list it. Plain mise use -g opencode gives OpenCode 2 on mise 2026.10.9 or later, and nix run nixpkgs#opencode gave OpenCode 2.0.32 on 20 October.

On Arch, sudo pacman -S opencode, which OpenCode's docs list as "Stable", installed OpenCode 2.1.1 from the extra repository on 20 October 2026. For OpenCode 1 on Arch, use opencode-bin from the AUR.

Copy and paste in the TUI needs a clipboard tool: xclip or xsel on X11, wl-clipboard on Wayland.

Install OpenCode on Windows

OpenCode's docs recommend WSL "for the best experience": install WSL, open its terminal and run the Linux script there. Your Windows files are under /mnt/c/; OpenCode suggests keeping the repository inside the WSL file system instead.

To run it natively:

Scoop has x64 and ARM64 builds. The .zip builds on GitHub's releases page work without any manager; OpenCode's docs say installing with Bun on Windows is not supported yet. The curl script runs in Git Bash, x64 only.

OpenCode 1 or OpenCode 2

OpenCode 2 is a new major version, and on 20 October 2026 opencode.ai's home and download pages and OpenCode's README install it. OpenCode's docs at opencode.ai/docs, GitHub's latest release and the Windows package managers still install OpenCode 1.

Both install a command called opencode, and OpenCode 2's migration guide says not to keep them side by side: remove a package-managed OpenCode 1 first; the OpenCode 2 script replaces the OpenCode 1 binary. What changes:

• Plugins. OpenCode 1 plugins do not run in OpenCode 2; they need porting.
• The server API and its clients are new, so integrations that call OpenCode's server need porting too.
• Terminal settings move from tui.json to one ~/.config/opencode/cli.json, migrated on first start.
• What carries over: opencode.json, agents, commands, skills and AGENTS.md are read from the same places. A CLAUDE.md is not read as a fallback any more.
• Windows: OpenCode 2's docs say Windows package managers are not supported, so Scoop and Chocolatey carry OpenCode 1 only. On Windows, OpenCode 2 comes from npm or a standalone .zip, for x64, x64 without AVX2 (baseline) or ARM64.

OpenCode 2 also keeps sessions in a new session_v2 table, in the same opencode.db file.

First run: connect a model

OpenCode comes with a few free models, so it answers before you connect anything. /connect adds a provider: an API key from one of more than 75, OpenCode's own Zen or Go, or a subscription you sign in with — ChatGPT Plus or Pro, GitHub Copilot or GitLab Duo. A Claude Pro or Max plan is not one of them: OpenCode's providers page says Anthropic prohibits it. What each option costs is in OpenCode pricing.

Outside the TUI, opencode auth login does the same. OpenCode 1 keeps keys in ~/.local/share/opencode/auth.json. Tab switches between the build agent, which edits, and plan, which does not.

Where OpenCode keeps its files

The folders are the same on every system, Windows included: under your home folder, not AppData.

Update OpenCode

opencode upgrade updates to the latest version, and opencode upgrade 1.18.34 to a given one. It detects how you installed it; --method names it when it guesses wrong. By default OpenCode 1 also downloads updates itself when it starts, unless a package manager installed it; "autoupdate": "notify" or false in opencode.json changes that.

Uninstall OpenCode

opencode uninstall lists what it will remove and asks first. The two versions remove different things, which is worth knowing before you press enter. I ran --dry-run on both in a scratch home folder on 9 October:

• OpenCode 1 removes the binary and all four folders: data (your sessions and logins), cache, config and state. Add --keep-data (-d) and --keep-config (-c) to keep them.
• OpenCode 2 removes the cache only and keeps sessions, settings and state. An npm or Homebrew install is removed through that manager; a script install leaves the binary for you to delete.

A package-manager install comes out with that manager: brew uninstall opencode, npm uninstall -g opencode-ai, scoop uninstall opencode. OpenCode Desktop is removed like any other app.

Common install errors

• opencode: command not found after the script. The script added ~/.opencode/bin to your rc file; the terminal you ran it in has not read it. Open a new one. The README lists OPENCODE_INSTALL_DIR and XDG_BIN_DIR to choose the folder, but the script served on 20 October reads neither and always uses ~/.opencode/bin.
• Windows: "not a valid application for this OS platform". npm left a 479-byte placeholder opencode.exe because the package's postinstall step did not run or was blocked. Issues #41370 and #36737, both closed now, describe it. The workarounds there: run the package's postinstall.mjs by hand, or npm install -g --allow-scripts=opencode-ai opencode-ai. Scoop avoids npm altogether.
• "It seems your package manager failed to install the right opencode CLI package". npm's install step found no build for your platform, for example opencode-linux-x64. The message names the packages to install by hand; issue #23601 hit an older wording of it on WSL2.
• illegal hardware instruction, or a silent hang. The default x64 build needs AVX2, which older CPUs lack (issues #8345 and #12553). The script picks the -baseline build on such machines, and so does npm's install step when it runs; it does not when install scripts are blocked, as with Bun without --trust or --ignore-scripts.
• Windows Defender flags it as a trojan. Reported after an update through npm in issue #7655, closed in March 2026.
• The wrong version runs. Two installs, and whichever folder comes first on your PATH wins. which -a opencode on macOS and Linux, where opencode on Windows, lists them; remove one.
• OpenCode 2 on Windows. Open issues report a timeout waiting for its background service (#49034) and no in-place upgrade from PowerShell (#51755). Native Windows users may prefer OpenCode 1 from Scoop for now.

When something else fails, opencode --print-logs prints the log to the terminal, and the log files are in ~/.local/share/opencode/log/.

What it took on my Mac

9.5 s

OpenCode 1.18.35 with its script

144 MB

the one binary it leaves

186 MB

OpenCode 2.0.26, same method

One run each on an Apple silicon Mac on 9 October 2026, into a scratch home folder; your network decides the time. npm install of opencode-ai took 7 seconds.

Run OpenCode in Caprock

⤢

Caprock is a free, open-source desktop app for macOS, Windows and Linux that records every coding agent on the machine and runs their own terminal programs in tabs. Once opencode is installed, New agent offers OpenCode next to Claude Code, Codex, Gemini CLI, Grok Build and Hermes Agent. Caprock finds the binary on your shell's PATH, in Homebrew's folders and in ~/.opencode/bin, where the script puts it, so a fresh install needs no setup.

• The OpenCode TUI in a tab, in the project you pick or a new worktree, with an optional model in OpenCode's provider/model form and a permission choice: Plan starts OpenCode's plan agent, Accept edits makes shell commands ask first.
• Cost per session and per project. OpenCode computes each call's cost; Caprock reads it from OpenCode's database, read-only, and adds it to the same table as your Claude Code and Codex sessions. Like OpenCode's figure, it is modelled from list prices, not a bill.
• History from before Caprock. Sessions already in OpenCode's database show up, searchable beside Claude's, and an ended one continues in a new tab.

Caprock reads both versions: OpenCode 1's session table and OpenCode 2's session_v2, counting each message once in a database OpenCode 2 has upgraded. It starts OpenCode 1 with --port, -m and --agent, and OpenCode 2 with --standalone --session <id>, passing the model and agent through OPENCODE_CONFIG_CONTENT. Both are verified on macOS against real installs, and OpenCode 2 also in a Debian container on Linux; otherwise, on Windows and Linux, they are covered by Caprock's tests. More on running both in one window is in OpenCode desktop app.

Which install to pick

• The script — macOS, Linux or WSL, and you want opencode upgrade to handle updates.
• Homebrew's tap — you manage everything else with Homebrew.
• Scoop or Chocolatey — native Windows without Node.js.
• npm — Node.js is already there, or you pin versions per machine.
• OpenCode 2 — you want the new version and use no OpenCode 1 plugins.
• OpenCode with Claude Code and Codex in one record — install OpenCode 1 or 2, then install Caprock.