Quick answer
Treat OpenCode V2 as a planned migration, not a blind update
Choose V2 when its current CLI and desktop capabilities suit your workflow and you have time to validate the change. Keep V1 available until you have checked models, credentials, agents, permissions, MCP servers, plugins, editor clients, and real project tasks. A small personal setup can start in a sample project; a team or a repository with custom plugins should move in stages.
If you see the shorthand OpenCode 2, it refers to the V2 major line covered here. The version name matters because installation and compatibility steps differ from a routine V1 update.
The official migration guide says supported V1 configuration and file-based definitions are intended to keep working, and the familiar opencode command remains. The important caveat is that V1 plugins do not run on V2, the server API and clients have new contracts, and terminal preferences move to a global cli.json file. Plan a compatibility check even if you do not convert your main config.
This guide brings the official install channels, a V1-to-V2 comparison, and a cautious checklist together. It does not promise that historical session databases are converted. For model choice, API credentials, and plan cost, see the dedicated model guide, provider guide, and plan comparison.
OpenCode V1 vs V2: changes that affect a real workflow
The version number alone does not show migration effort. Focus on the surfaces your setup actually uses: terminal client, plugins, server API, and configuration. Supported project files are a different category from executable plugin code or API clients.
| Area | V1 | V2 and migration impact |
|---|---|---|
| CLI command | opencode | The command name is still opencode. V1 and V2 are not installed side by side by default. |
| Supported config and files | V1 config plus files under .opencode/ | Supported fields, agents, commands, and skills are intended to continue working; verify your provider and permission behavior. |
| Plugins | V1 plugin API and entry points | New plugin API. V1 plugins need a port before they can run. |
| Server API and clients | V1 API contract and generated clients | New contracts. Integrations need a V2-compatible client and tests. |
| Terminal preferences | Layered tui.json or tui.jsonc files | Supported settings migrate to the terminal client's global cli.json; review the result. |
| Install channel | V1 package or installer | Use a V2-specific official channel; a package-managed V1 may need removal first. |
This table is a boundary map, not a promise that every V1 field is supported. The migration documentation lists accepted-but-unsupported values and warns that ignored legacy fields can produce warnings. Check the current source guide before changing configuration that controls security, provider access, or automation.
Should you upgrade OpenCode to V2 now?
Make the decision from compatibility and reversibility, not from the major number alone. A personal setup that uses built-in features has a different migration cost from a repository with custom plugins and an editor integration.
A V2 trial is a reasonable next step when
- Your workflow mainly uses supported config, providers, built-in commands, agents, skills, and MCP, and you can verify each one in a sample project.
- You want the V2 CLI or desktop experience and can keep a working copy of your current setup during the trial.
- Your plugins or server clients already have a V2 release, or you have an owner and time to port and test them.
Wait before replacing V1 when
- A V1 plugin, server endpoint, IDE client, or automation job is business-critical and has not been tested against the V2 contract.
- You cannot restore your current package, config, or session data if the new workflow fails.
- The only reason is an update prompt: an in-place V1 update is not the same procedure as moving to the V2 major line.
If unsure, test in a disposable project and record the command, package manager, OpenCode version, and expected result. That gives you a rollback point and a concrete compatibility list instead of relying on a general claim that a new major version is better.
How to install OpenCode V2 through an official channel
The current V2 introduction lists these terminal install channels. Pick the one that already manages software on your machine and follow its current official instructions. Do not copy an old V1 package command into a V2 migration.
| Channel | Current command or route | Practical note |
|---|---|---|
| Shell installer | curl -fsSL https://opencode.ai/v2/install | bash | The V2 endpoint is explicit. The migration guide says this installer replaces the V1 binary. |
| Homebrew | brew install anomalyco/tap/opencode-v2 | Use the V2 formula; identify and remove a package-managed V1 install first when required. |
| npm | npm install -g @opencode/cli | This is the V2 package name. Its postinstall selects a native binary for the platform. |
| Bun | bun install -g --trust @opencode/cli | The official docs require allowing the package install script. |
| pnpm | pnpm add -g --allow-build=@opencode/cli @opencode/cli | The official docs require the allow-build flag for the package script. |
| Windows | Official standalone CLI binary | The V2 docs say Windows package managers are not supported; use the official platform binary instructions. |
For npm, Bun, pnpm, Yarn, Vite+, or AUR, check the V2 intro for current syntax and platform support. On October 3, 2026, npm's @latest tag for @opencode/cli resolved to 2.0.22. This is a dated observation, not a pinned recommendation. Check the live package or official docs again before installing.
Before installing, identify how V1 was installed. The official migration guide says a package-managed V1 may need to be removed first because both major versions use the opencode command; the V2 curl installer replaces the V1 binary. Do not delete shared config or data as part of package removal.
How to migrate from OpenCode V1 to V2 safely
Keep the first pass reversible. The aim is to establish that V2 launches and the project works, not to rewrite every config file on day one. Use the official migration instructions for the exact package and operating system you have.
- Record the install owner. Run
opencode --version, then inspect your package manager or binary path so you know which V1 installation could be replaced. - Make a restorable copy. Back up global and project config,
.opencode/files, plugin source, client settings, and data you cannot recreate. Verify that the backup can be read; keep secrets out of Git. - Install V2 by its official channel. If V1 came from a package manager, follow that manager's removal and V2 installation path; do not assume a second
opencodecommand will appear. - Test in a low-risk project. Check the model, provider credentials, agents, permissions, MCP servers, commands, and skills against a known task. Confirm a small change and inspect its diff.
- Port extensions separately. Use the V2 plugin migration guide for V1 plugins and test every hook or server endpoint used by your workflow before rolling the new version into the main project.
Leave supported V1-shaped config in place during the first verification pass. The official guide says V2 normalizes supported legacy config without rewriting the source; converting to native V2 config is optional. Conversion later makes it easier to identify which change caused a regression.
What carries over automatically, and what needs a manual check?
Treat automatic compatibility as limited to behavior the current V2 guide explicitly supports. The distinction below helps answer OpenCode V2 compatibility questions without implying every old field or extension will keep working.
| Surface | Expected starting point | What to verify |
|---|---|---|
| Supported config | V2 reads the same global and project locations and normalizes supported V1 fields in memory. | Check warnings and behavior for your provider, permissions, MCP, and model settings. |
| Agents, commands, skills | Existing supported file definitions under .opencode/ are intended to keep working. | Run a representative agent and command; check custom paths and referenced scripts. |
| Plugins | V1 plugin implementations do not run on V2. | Port the entry point, hooks, tools, events, options, and cleanup path; test the installed package. |
| Server API and clients | The API and generated clients have new contracts. | Update callers and test auth, request shapes, responses, and failure handling. |
| Terminal preferences | Supported global tui.json(c) settings migrate to the terminal client's global cli.json. | Review migrated preferences. Project-local TUI config is not migrated as a project file. |
| Legacy fields | Some schema-accepted V1 fields have no V2 equivalent and are intentionally ignored with warnings. | Compare config with the unsupported-fields list; do not dismiss a warning without understanding it. |
| Session history | The core migration guide does not promise bulk conversion of historical databases. | Keep a separate data backup and verify sessions you need; a successful CLI launch does not prove history migrated. |
The V2 guide treats supported behavior that breaks as a compatibility issue and lists unsupported fields separately. A successful startup is only the first check: your own tools, session workflow, and security rules still need a functional test.
Verify OpenCode V2 before removing your V1 fallback
Run a short acceptance pass in a sample project and keep the result with your upgrade notes. That turns an impression into a repeatable checklist for another machine or teammate.
- Confirm
opencode --versionreports the V2 line you intended and that the executable comes from the expected install path. - Connect the expected provider, list models, and run one read-only prompt before allowing edits. Never expose credentials in logs.
- Exercise one command or agent, one MCP server, and every plugin or client integration required for work.
- Check permission decisions and project boundaries with a safe task; inspect changed files and the Git diff.
- Review startup warnings and migrated
cli.jsonpreferences. Resolve unsupported legacy fields before depending on them.
If a critical check fails, stop using V2 for that workflow and return to the preserved V1 installation or package. Do not point V1 at V2-only config. The rollback command depends on the package manager, so keep user data separate from the install package.
For routine updates after V2 is already installed, the V2 CLI documents opencode upgrade, with update as an alias. That is distinct from moving from the V1 major line.
OpenCode V2 migration FAQ
Is OpenCode V2 a normal update from V1?
No. It is a major-line migration. Both use the opencode command and package-managed V1 and V2 are not installed side by side by default. Identify the install method and follow the official migration guide.
Do I have to rewrite my OpenCode config for V2?
Not necessarily. The official guide says supported V1 configuration is read and normalized without rewriting the source file. Inspect warnings and verify your provider, permissions, and MCP behavior.
Will my V1 OpenCode plugins work on V2?
No. V1 plugin implementations do not run on V2. Port their entry point and behavior using the official plugin migration guide, then test the installed package.
How do I install OpenCode V2 with npm?
The current V2 docs use npm install -g @opencode/cli. Check the current V2 intro and package page for platform support and install-script requirements.
Which command updates OpenCode V2?
For an installation already on V2, the CLI documents opencode upgrade and the update alias. Moving from V1 has separate package-removal and installation guidance.
Does upgrading to V2 migrate all session history?
The core migration guide does not promise bulk conversion of historical session databases. Back up important data and verify the sessions you need before switching your daily workflow.
Official OpenCode references
Installation commands and compatibility statements were checked against first-party documentation on October 3, 2026. Package versions and instructions can change, so verify them again before a major upgrade.