Installation

This guide covers every method for installing opencode on Linux, macOS, and Windows. Choose the option that best fits your environment.

Prerequisites

Before installing opencode, ensure your system meets the following requirements:

Terminal Emulator

opencode's primary interface is a Terminal User Interface (TUI) that requires a modern, feature-rich terminal emulator. The following terminals are recommended:

Terminal	Notes
WezTerm	GPU-accelerated, cross-platform, excellent font/color support
Alacritty	GPU-accelerated, minimal, fast
Ghostty	Native, GPU-accelerated, focused on correctness
Kitty	GPU-accelerated, feature-rich, kitten scripts

Most modern terminals that support true color (24-bit), Unicode, and mouse events will work. Avoid older terminals like the default macOS Terminal.app or basic Linux terminal emulators -- they lack the features opencode's TUI relies on.

Runtime Dependencies

opencode bundles its own Node.js runtime via the install script and standalone builds. If you install via npm, bun, pnpm, or yarn, you need:

• Node.js 18.0.0 or later (for npm/pnpm/yarn installations)
• bun 1.0.0 or later (for bun installation)

Check your Node.js version:

node --version

API Keys

You need at least one LLM provider API key to use opencode. See the Quick Start guide for provider setup.

Git

opencode uses git for automatic snapshots and undo functionality. Ensure git is installed and configured:

git --version
git config --global user.name "Your Name"
git config --global user.email "your@email.com"

Install Methods

Install Script (Recommended)

The install script detects your OS and architecture, downloads the appropriate binary, and places it in your PATH. This is the recommended approach for most users.

curl -fsSL https://opencode.ai/install | bash

The script supports the following environment variables:

Variable	Default	Description
OPENCODE_VERSION	latest	Install a specific version (e.g., 0.5.0)
OPENCODE_DIR	~/.opencode	Installation directory
OPENCODE_DRY_RUN	unset	If set, prints what would be done without executing

Example with version pinning:

curl -fsSL https://opencode.ai/install | OPENCODE_VERSION=0.5.0 bash

npm

Install opencode globally via npm. This requires Node.js 18+.

npm install -g opencode-ai

To install a specific version:

npm install -g opencode-ai@0.5.0

To update:

npm update -g opencode-ai

bun

bun offers faster installation times than npm. Requires bun 1.0+.

bun install -g opencode-ai

pnpm

For pnpm users:

pnpm install -g opencode-ai

yarn

For yarn users:

yarn global add opencode-ai

After installing via yarn, ensure the yarn global bin directory is in your PATH:

yarn global bin
# Add the output to your shell profile if not already in PATH

Homebrew (macOS / Linux)

opencode is available via a custom Homebrew tap:

brew install anomalyco/tap/opencode

To update:

brew update && brew upgrade anomalyco/tap/opencode

Arch Linux

Two packages are available in the AUR:

Stable release (pacman):

sudo pacman -S opencode

Binary package (AUR helper, e.g., paru):

paru -S opencode-bin

The opencode package builds from source. The opencode-bin package installs the pre-built binary for faster installation.

Windows

WSL (Recommended)

The best way to run opencode on Windows is via WSL 2 (Windows Subsystem for Linux).

1. Install WSL 2:

   wsl --install

2. Launch your WSL distribution and install opencode:

   curl -fsSL https://opencode.ai/install | bash

3. Install a modern terminal like WezTerm or Windows Terminal for the best TUI experience.

Chocolatey

choco install opencode

Scoop

scoop bucket add anomalyco https://github.com/anomalyco/scoop-bucket.git
scoop install opencode

npm on Windows

npm install -g opencode-ai

Docker

Run opencode in a containerized environment. This is useful for CI/CD, testing, or ephemeral development environments.

docker run -it --rm \
  -v "$(pwd):/workspace" \
  -v "$HOME/.config/opencode:/home/opencode/.config/opencode" \
  -e OPENCODE_API_KEY=your-key \
  ghcr.io/anomalyco/opencode

The Docker image is based on a minimal Linux distribution and includes the opencode binary. Mount your project directory as /workspace to give opencode access to your code.

To use the TUI interactively:

docker run -it --rm \
  -v "$(pwd):/workspace" \
  -v "$HOME/.config/opencode:/home/opencode/.config/opencode" \
  ghcr.io/anomalyco/opencode

Mise (Version Manager)

If you use mise to manage tool versions:

mise use -g opencode-ai

Verify Installation

After installation, verify opencode is available:

opencode --version

You should see output similar to:

opencode/0.5.0 linux-x64 node-v22.14.0

Test that the TUI launches:

opencode

Press Ctrl+C to exit. If the TUI displays correctly, installation was successful.

Auto-Update Behavior

opencode supports automatic updates. When a new version is available, you'll see a notification in the TUI. You can update with:

opencode upgrade

To update to a specific version:

opencode upgrade 0.6.0

To disable auto-update checks, set the following in your config:

{
  "upgrade": {
    "check": false
  }
}

Troubleshooting Installation

Command Not Found

If opencode is not found after installation, the install location may not be in your PATH. Common install locations:

Install Method	Binary Location
Install Script	~/.opencode/bin
npm / bun / pnpm / yarn	npm global bin directory (run npm bin -g)
Homebrew	/opt/homebrew/bin (Apple Silicon) or /usr/local/bin (Intel)
Arch Linux	/usr/bin

Add the install directory to your shell profile:

export PATH="$PATH:$HOME/.opencode/bin"

Permission Denied

If you encounter permission errors with the install script, your system may require sudo, though this is rare. The install script places binaries in ~/.opencode/bin by default, which does not require root.

Docker Permission Errors

On Linux, running Docker may require sudo or membership in the docker group:

sudo usermod -aG docker $USER
# Log out and back in for changes to take effect

Terminal Doesn't Display TUI Properly

If the TUI renders incorrectly, your terminal may not support the required features. Try:

1. Switch to a recommended terminal (WezTerm, Alacritty, Ghostty, Kitty)
2. Ensure TERM is set to xterm-256color or tmux-256color
3. Disable any TUI-overriding wrappers in your shell (e.g., tmux with legacy settings)

Run opencode in pure non-interactive mode to bypass TUI rendering:

opencode --pure run "test connection"

What's Next

• Quick Start -- Get set up with a provider and start coding
• Key Features -- Learn about opencode's capabilities
• CLI Usage -- Explore command-line options and scripting