How to Install OpenCode on Windows with WSL in 2026
Learn how to install OpenCode on Windows using WSL 2 and Ubuntu. Includes the exact commands, model setup, project best practices, troubleshooting, and safer AI coding workflows.
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.
Section why-wsl screenshotRun 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.
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.
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.
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.
Section troubleshooting screenshotUse 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.
Yes. The official documentation also lists Chocolatey, Scoop, npm, Docker, Mise, and prebuilt releases. WSL is recommended for the best Windows compatibility and performance.
Microsoft documents the one-command install for Windows 10 version 2004 and higher, build 19041+, and Windows 11.
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.
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.
Run `wsl --list --verbose` in PowerShell. If Ubuntu shows version 1, use `wsl --set-version Ubuntu 2`.
Related Articles
AI Assistant Development Cost in 2026: RAG Chatbots, CRM Integrations, Guardrails, and Support
A practical buyer guide to AI assistant development cost in 2026: prototypes, RAG chatbots, knowledge-base assistants, CRM and website integrations, guardrails, evaluations, monitoring, and support.
AI-assisted attacks and prompt injection in 2026: the new attack surface for AI products
AI-assisted attacks and prompt injection in 2026: the new attack surface for AI products. A practical PAS7 Studio security guide with threat model, controls, rollout checklist, pitfalls, and sources.
AI for landing page development: where it speeds up launches and where it hurts conversion
A practical research piece on using AI for landing page development: v0, Webflow AI, Builder.io, Framer-like builders, UX generation, copy, SEO, personalization, A/B testing, template risk, accessibility, security and technical debt.
AI SEO / GEO in 2026: Your Next Customers Aren’t Humans — They’re Agents
Search is shifting from clicks to answers. Bots and AI agents crawl, cite, recommend, and increasingly buy. Learn what AI SEO / GEO means, why classic SEO is no longer enough, and how PAS7 Studio helps brands win visibility in the agentic web.
Professional development for your business
We create modern web solutions and bots for businesses. Learn how we can help you achieve your goals.