Upgrade Guide

Use this guide when you want to move from one OpenCode version to a newer one. It covers the moving parts (CLI, TUI, Web, Desktop, SDK), the configuration files that may need updates, and the steps to take if something goes wrong.

Before you start

Note your current version: opencode --version.
Pick the target version from the releases page.
Read the release notes between those two versions.
Back up your configuration files (opencode.json, ~/.opencode/, any workspace-specific configs).

Component relationships

OpenCode ships several components from the same release line. In general, keep them on the same minor version to avoid surprises.

Component	Where it runs	Notes
CLI	Terminal on your machine	The reference for everything else
TUI	Terminal on your machine	Built on the CLI
Web	Browser + local server	The local server is the same binary as the CLI
Desktop	Native window (macOS, Windows, Linux)	Still in beta; tracks the CLI in feature parity
SDK	Embed in your own app	Tracks CLI public API

If you only use the CLI and TUI, you can upgrade in place. If you also run the Web server or Desktop client, plan to upgrade them together so behaviour stays consistent.

Configuration migrations

OpenCode preserves backward compatibility for most configuration, but a few keys have been renamed or replaced. Common examples:

The legacy tools boolean config was merged into the permission config; the old key is still accepted but emits a deprecation warning. Move the rules to permission at your convenience.
Custom tool and command definitions in ~/.opencode/ follow the current schema documented under Commands and Tools.

If opencode doctor or the TUI reports a deprecation warning, follow the suggested migration before the next major bump.

Model replacements

Model availability changes frequently. Before you upgrade:

Check the Models overview for newly deprecated models in the version you are moving to.
Replace pinned model IDs (for example, a dated <provider>/<model> reference) with a stable alias or the current model name recommended by your provider.
If you use OpenCode Zen, review the current catalog on opencode.ai/zen for the active models and pricing.

Upgrade steps

The exact command depends on how you installed OpenCode. Pick your platform:

macOS / Linux (install script): re-run the script — it detects your current version and replaces it in place. curl -fsSL https://opencode.ai/install | bash
Homebrew: brew upgrade anomalyco/tap/opencode (or opencode if you use the official formula).
npm / pnpm / yarn: npm i -g opencode-ai@latest (or the equivalent for your package manager).
Scoop / Chocolatey: scoop update opencode or choco upgrade opencode.
Docker: pull the new image and restart your container; the Docker guide lists the supported tags.
Desktop app: use the in-app updater (Help → Check for Updates) or reinstall from the downloads page.

After the upgrade:

Run opencode --version to confirm the new version.
Run opencode doctor (when available) or the TUI to surface any configuration warnings.
Re-run a small representative task before resuming normal use.

Rolling back

If the upgrade breaks a critical workflow:

Reinstall the previous version using the same install method.
Restore your backed-up opencode.json and any custom config in ~/.opencode/.
Re-pin model IDs if a newer default is no longer compatible with your provider.
Open a GitHub issue with the failing version, reproduction steps, and any error output.

When to skip an upgrade

You do not need to upgrade every release. Skip a version when:

The release notes do not mention any change that affects you.
A critical plugin or provider integration you rely on has not been validated against the new version.
You are mid-incident and the new version does not contain a fix for the issue you are working on.