OpenCode Won't Install? The Common Errors and Their Fixes

Table of Contents

• First: is this an install error or a connection error?
• Error 1: error: opencode-ai's postinstall script was not run.
• Error 2: brew install opencode does not work
• Error 3: command not found: opencode
• Error 4: I installed on Ubuntu and cannot find the package
• Error 5: I have v1 and want to move to v2
• Error 6: the installer asks for permissions or fails with EACCES
• Error 7: the TUI opens but the model does not answer
• Error 8: it worked and then ran out mid-afternoon
• Error 9: I installed twice and now behavior is weird
• Quick checklist
• Keep reading

First: is this an install error or a connection error?

This distinction saves you hours, and almost nobody makes it.

If the TUI opens — if you see the OpenCode interface in your terminal — the install worked. Anything wrong from there on is configuration: the API key, the provider, the quota. Do not reinstall anything.

If the command does not exist or the installer aborts, then it really is the install, and read on.

Error 1: error: opencode-ai's postinstall script was not run.

This is the most-searched error, and it has two distinct causes people conflate.

Cause A: your package manager blocked the script. The npm package uses a trusted postinstall script to download the native binary for your platform. bun and pnpm do not run postinstall scripts without explicit permission, by security design. If you installed with either one without the flag, the package is half-installed: it exists, but with no binary.

# bun
bun install -g --trust @opencode/cli

# pnpm
pnpm add -g --allow-build=@opencode/cli @opencode/cli

Cause B: you are on the old package. Look at the name in the error: opencode-ai. That is the old package. The v2 one is @opencode/cli. If you followed a 2025 tutorial, you installed the wrong one.

npm uninstall -g opencode-ai
npm install -g @opencode/cli

Run the uninstall even if you think you do not have it. Two packages registering the same opencode command on your PATH produce errors that look nothing like their cause.

Error 2: brew install opencode does not work

It does not work because it does not exist. The v2 docs are explicit: Homebrew, AUR, Scoop and Chocolatey are not supported.

If you searched brew install anomalyco/tap/opencode and it got you nowhere, the tap is not down: it is not an official channel. Same for any loose .exe from a mirror.

The channels that do work:

Route	Command
npm	npm install -g @opencode/cli
bun	bun install -g --trust @opencode/cli
pnpm	pnpm add -g --allow-build=@opencode/cli @opencode/cli
yarn	yarn global add @opencode/cli
Official script	curl -fsSL https://opencode.ai/v2/install | bash
Docker	ghcr.io/anomalyco/opencode with a version tag

Any tutorial handing you a brew install for OpenCode is from 2025 or an unofficial source. The current list is in the OpenCode documentation.

Error 3: command not found: opencode

This is almost never the install. It is the PATH.

1. Open a new terminal. If you installed with the curl script, the directory may not be loaded in your current session.
2. If you would rather not close the terminal, reload your shell: source ~/.bashrc or source ~/.zshrc.
3. Check where the binary landed: npm bin -g prints npm's global directory. If that directory is not on your $PATH, add it.

On Windows this error is more common because npm's global prefix sometimes does not end up on the system PATH when Node is installed. That is a Node problem, not an OpenCode one: fix it once and it fixes every global package you have.

Error 4: I installed on Ubuntu and cannot find the package

There is no apt or snap package. On Linux you install exactly as on macOS: through npm/bun/pnpm/yarn, or with the official v2 script.

If you used the curl script on Ubuntu and the command does not appear, go back to error 3: it is the PATH. The script installs into its own directory that your shell has to know about.

Error 5: I have v1 and want to move to v2

The version jump changed the package name, and that is what breaks upgrades. Running npm update -g on the old package does not get you to v2, because they are different packages in the registry.

npm uninstall -g opencode-ai
npm install -g @opencode/cli
opencode --version

Check the version at the end. If it still reports the old one, you have an orphaned binary in another PATH directory: find it with which -a opencode and delete the one that does not belong.

Error 6: the installer asks for permissions or fails with EACCES

The classic global-npm problem on Linux and macOS: the global directory belongs to root and your user cannot write to it.

The wrong and tempting fix is sudo npm install -g. It works, but it leaves root-owned files in your home and will cause problems later. The right fix is to change npm's prefix to a directory in your own home, or use a Node version manager like nvm, fnm or volta, which install everything under your home and remove the problem at the root.

Error 7: the TUI opens but the model does not answer

Repeating the warning from the top, because this is where most people reinstall for nothing: this is not an install error.

Run /connect inside the TUI. Check that the API key is the right one and that the selected provider is the one you paid for. If you use Z.ai's Coding Plan, the endpoint matters: there is an Anthropic-compatible one and an OpenAI-compatible one, and picking wrong means your plan quota never gets drawn down. That is covered in the Z.ai Coding Plan setup.

Error 8: it worked and then ran out mid-afternoon

Also not a bug. That is your plan's usage ceiling.

OpenCode Go applies limits per time window, not a single monthly quota. If you ran dry mid-afternoon, you hit the 5-hour window cap, not the monthly one. The exact numbers and how they split are in OpenCode Go: price and limits.

Error 9: I installed twice and now behavior is weird

Symptoms: the command reports a different version than the one you installed, or config changes do not take effect.

which -a opencode

That command lists every path where the binary exists. If it returns more than one, you have competing installs: typically one from npm and one from the curl script, or one from a brew attempt long ago. Delete the ones you do not want and keep a single one.

Quick checklist

If you do not want to read all of the above, this is the diagnostic order:

1. Does the TUI open? → the problem is not the install, it is /connect.
2. which -a opencode → if more than one, clean up.
3. npm uninstall -g opencode-ai → remove the old package.
4. npm install -g @opencode/cli → install the v2 one.
5. Fresh terminal → rule out the PATH.
6. On bun or pnpm → add --trust or --allow-build.
7. Never brew.

Keep reading

• The full tutorial: How to install OpenCode step by step
• If the problem is quota: OpenCode Go: price and limits
• If the problem is the endpoint: Z.ai Coding Plan: base URL and setup