How to Install OpenCode on Windows with WSL in 2026

before you start

Why use WSL for OpenCode on Windows?

OpenCode can be installed on Windows through several routes, including npm, Chocolatey, Scoop, Docker, and prebuilt releases. The official documentation recommends WSL for the best Windows experience because it provides better performance and compatibility with OpenCode's terminal-oriented features. [1]

WSL gives you a real Linux user space inside Windows without a traditional virtual machine or dual boot. That matters for Node.js projects, shell commands, Git hooks, package managers, and tools that assume a Unix-like environment. Microsoft documents wsl --install as the one-command setup for WSL and Ubuntu on supported Windows versions. [2]

The mental model is simple: Windows remains your desktop, Ubuntu provides the Linux development environment, and WSL 2 connects them.

step 1

Install WSL 2 and Ubuntu

Run these commands from an elevated PowerShell window, then finish the first-time Ubuntu setup.

Open PowerShell as Administrator

Open the Start menu, search for PowerShell, right-click it, and choose Run as administrator.

Install WSL

Run wsl --install. Microsoft says this enables the required components and installs Ubuntu by default on supported Windows 10 and Windows 11 systems. [2]

Restart Windows

Restart when Windows asks. If wsl --install only shows help text because WSL is already present, use wsl --list --online and then install a distribution explicitly with wsl --install -d Ubuntu. [2]

Complete Ubuntu setup

Launch Ubuntu from the Start menu. Choose a Linux username and password. This account is separate from your Windows login and will be used for development commands.

Confirm WSL 2

From PowerShell, run wsl --list --verbose. Your Ubuntu distribution should show version 2. If it shows version 1, run wsl --set-version Ubuntu 2. [2]

WSL check

Run wsl --list --verbose and confirm that Ubuntu is using WSL 2 before installing OpenCode.

step 2

Install OpenCode inside Ubuntu

Open Ubuntu

Use the Ubuntu app or Windows Terminal. You should see a Linux shell prompt, usually ending with $, rather than a PowerShell prompt.

Update the package list

Run sudo apt update. This keeps the Ubuntu package metadata current before you install development dependencies.

Install OpenCode

The official script is curl -fsSL https://opencode.ai/install | bash. The npm route is npm install -g opencode-ai if Node.js is already installed in Ubuntu. [1]

Check the command

Run opencode --version. If the command is not found, restart the Ubuntu terminal or check that the install directory is included in your Linux PATH.

Important

Install OpenCode in the Linux environment where your project and its dependencies run. A Windows-global install and a Linux-global install are separate environments.

step 3

Open a project and connect a model

Use the Linux filesystem

Create a workspace such as mkdir -p ~/projects and keep active repositories under /home/<user>/projects. Accessing files through /mnt/c works, but Linux-side projects are usually a better default for performance.

Clone or open the repository

For example: cd ~/projects && git clone <repository-url> && cd <repository-folder>. Keep secrets out of prompts and never commit API keys.

Start OpenCode

Run opencode. In the TUI, use /connect to choose OpenCode Zen or another supported provider and paste the provider API key.

Initialize project context

Run /init. OpenCode analyzes the repository and creates AGENTS.md. Review the instructions and commit them if they describe real project conventions. [1]

Start with a small task

Ask OpenCode to explain a file, add one test, or fix one reproducible bug. Reference files with @, ask for a plan for risky work, and require a test or typecheck.

fixes

Common OpenCode and WSL problems

opencode: command not found — Confirm that you installed it inside Ubuntu, not only in PowerShell. If you used npm, run which node, which npm, and npm install -g opencode-ai inside Ubuntu. Restart the shell after installation if necessary.

The project feels slow — Avoid putting active repositories under /mnt/c/Users/... when performance matters. Clone or move the project into your Linux home directory, such as ~/projects/my-app, and edit it through VS Code's WSL integration if desired.

Ubuntu is using WSL 1 — Check with wsl --list --verbose, then run wsl --set-version Ubuntu 2. New installations through wsl --install use WSL 2 by default, but older setups may need an upgrade. [2]

Installation hangs at 0% — Microsoft documents wsl --install --web-download -d Ubuntu as an alternative when the distribution download stalls. [2]

A model does not respond — Check /connect, the provider API key, billing or quota, and the selected model. OpenCode is the client; model availability and limits are controlled by the provider.

Most setup problems have a short path to a fix: check the Linux PATH, keep active projects in the Linux filesystem, and make sure the distribution is on WSL 2.

best practices

A safer Windows workflow for AI coding

Use a Git branch

Keep OpenCode changes isolated and reviewable.

Start in Plan mode

Use planning before authentication, payments, migrations, infrastructure, or large refactors.

Protect secrets

Do not paste .env files or production credentials into prompts. Configure permissions so sensitive paths are denied or require approval.

Verify the result

Ask OpenCode to run the narrowest relevant test, typecheck, linter, or build.

Use Windows Terminal or VS Code WSL

A consistent terminal and editor integration makes the Windows/Linux boundary easier to understand.

FAQ

Can I install OpenCode directly on Windows without WSL?

Yes. The official documentation also lists Chocolatey, Scoop, npm, Docker, Mise, and prebuilt releases. WSL is recommended for the best Windows compatibility and performance.

What Windows versions support wsl --install?

Microsoft documents the one-command install for Windows 10 version 2004 and higher, build 19041+, and Windows 11.

Should OpenCode be installed in PowerShell or Ubuntu?

For the WSL workflow, install and run OpenCode inside Ubuntu. This keeps OpenCode, Node.js, package managers, and the project in the same Linux environment.

Why is my OpenCode project slow on Windows?

Projects accessed through /mnt/c can be slower for some workloads. Keep active repositories in the WSL Linux filesystem, such as ~/projects, and use a WSL-aware editor integration.

How do I check whether Ubuntu uses WSL 2?

Run `wsl --list --verbose` in PowerShell. If Ubuntu shows version 1, use `wsl --set-version Ubuntu 2`.

references

Official installation sources

OpenCode installation and Windows recommendations

Microsoft: install WSL and Ubuntu

OpenCode providers and model configuration

OpenCode permissions

Reviewed: 28 Jul 2026Applies to: Windows 10 version 2004+Applies to: Windows 11Applies to: WSL 2Applies to: UbuntuApplies to: OpenCode CLITested with: OpenCode official installation documentationTested with: Microsoft WSL installation documentation

The shortest reliable setup

Describe the task — first 15 minutes of consultation are free.