How to Update OpenCode Safely: Commands, Checks, and Rollback

Do not guess from the command name. Use the evidence on your machine. A version can be installed by a shell script, npm, Bun, Homebrew, an Arch package, a standalone Windows binary, or a package manager inside a container. Each path has its own file location and replacement behavior.

On Unix-like systems, command -v opencode and type -a opencode show which executable wins. On PowerShell, use Get-Command opencode | Format-List Source,Version. If more than one location appears, pause and remove the ambiguity before updating.

These examples are starting points taken from the current official installation paths. Package names, aliases, and platform support can change. Read the official page immediately before running a command, especially on a team machine.

V2 CLI installation

For a V2 installation, the CLI documents opencode upgrade and the update alias. Run it from a normal user shell, then repeat opencode --version. If the command is not available, the installation may be an older V1 package or a different binary on PATH.

opencode --version
opencode upgrade
opencode --version

npm, Bun, pnpm, and Homebrew

For npm, the current V2 package is @opencode/cli. A global reinstall is often the clearest recovery when the package manager owns the binary. Bun and pnpm may require an explicit permission flag for install scripts. Homebrew should update the formula that is already installed.

npm install -g @opencode/cli
bun install -g --trust @opencode/cli
pnpm add -g --allow-build=@opencode/cli @opencode/cli
brew upgrade anomalyco/tap/opencode-v2

Do not run every line. Choose one line that matches the installation evidence. Afterward, inspect the manager output for permission errors, skipped postinstall scripts, or a path outside the expected prefix. A successful package transaction is not proof that the shell is invoking the new executable.

Windows and scripted environments

The official V2 download page lists a Windows binary route rather than a Windows package-manager promise. In a managed workstation, replace the intended executable through the approved download path, then open a new PowerShell session so the command lookup is refreshed. In Docker or CI, update the image or lockfile intentionally and rebuild it; do not mutate a running container and call that a durable upgrade.

A version number answers only one question: which executable responded. A useful update check covers the operations that can fail after a package or binary change.

1. Confirm the binary. Run opencode --version and the platform-specific path command. Make sure both point to the same install channel.
2. Start a low-risk project. Use a disposable repository or a branch with a clean Git diff. Do not begin the first test in a production checkout.
3. Check provider and model access. Run a read-only prompt, list the expected model, and confirm that credentials are loaded without printing a secret.
4. Exercise permissions. Ask for a file read, a small proposed edit, and a command that should require approval. Confirm that your allow and deny rules still behave as expected.
5. Test extensions. Run one important agent, command, skill, MCP server, or plugin. Major-line extensions may need migration even when routine CLI updates do not.
6. Inspect the diff. Check changed files, generated output, logs, and the project configuration. A clean launch with an unexpected file change is not a clean result.

Write the result beside the version number: operating system, shell, install channel, provider, model, and the task you ran. This short record makes the next OpenCode update easier to compare and gives a teammate a reproducible rollback point.

Stop using the changed installation until you know whether the failure is a path problem, a package problem, or a compatibility problem. Keep the old package cache or installer when your team policy allows it, and keep the configuration backup separate from the executable.

When the command is not found

Open a new shell, rerun where opencode or command -v opencode, and compare the result with the package-manager prefix. A shell profile can point to an old global bin directory. Fix the path first; reinstalling repeatedly can create more copies.

When a provider or model fails

Compare the active config path and model ID with the pre-update note. Do not paste a secret into a bug report. If only one provider fails, test a read-only request with the same account and inspect the official provider notes before changing permissions.

When a plugin or MCP server fails

Disable the extension in a test project and confirm the core CLI works. Then check its release notes and compatibility boundary. If the extension is V1-only, follow the plugin guide or the MCP guide rather than downgrading blindly.

For a major V1-to-V2 move, use the documented migration and backup plan. Routine update troubleshooting should not silently turn into a major-version migration.

On October 18, 2026, the first-party OpenCode changelog showed v2.0.32 at the top, with entries dated October 16, 2026. The official download page listed the V2 shell installer, npm package, Bun, Homebrew, Arch, and platform binaries. This is a dated verification, not a promise that the same version will remain latest.

The page does not publish a guessed direct file URL, file size, or security scan result. Use the official download route for the platform you actually run, and record the version returned by opencode --version after installation.

Commands and version notes were checked on October 18, 2026. Software release information changes, so open the first-party pages again when you perform a later update.

• OpenCode changelog
• Official download page
• V2 CLI command reference
• OpenCode V2 migration guide
• Provider and API key guide
• Model selection guide
• Commands and TUI guide