Skip to main content

Windows & WSL

OpenCode supports Windows through multiple installation methods. For the best experience, Windows Subsystem for Linux (WSL) is recommended.

Installation Methods​

WSL provides native Linux compatibility on Windows, ensuring full terminal feature support and access to Unix developer tools.

# 1. Install WSL from PowerShell (Admin)
wsl --install

# 2. Install OpenCode inside WSL
curl -fsSL https://opencode.ai/install.sh | sh

WSL gives you:

  • Full terminal emulation and color support
  • Unix file permissions and symlinks
  • Native performance for file operations
  • Access to Linux package managers (apt, brew)
  • Seamless integration with VS Code and JetBrains via wslpath

Chocolatey​

choco install opencode

Chocolatey installs OpenCode system-wide and adds it to your PATH automatically.

Scoop​

scoop install opencode

Scoop installs to your user directory without admin rights and provides easy version management.

npm​

npm install -g opencode-ai

Requires Node.js 18 or later. The npm package is updated on every release.

Docker​

Run OpenCode in a Docker container without installing it directly:

docker run -it --rm `
  -v "${PWD}:/workspace" `
  -v "${env:USERPROFILE}\.opencode:/root/.opencode" `
  ghcr.io/anomalyco/opencode

For projects, mount the working directory and configuration:

docker run -it --rm `
  -v "C:\Projects\my-app:/workspace" `
  -v "${env:USERPROFILE}\.config\opencode:/root/.config\opencode" `
  -e ANTHROPIC_API_KEY `
  ghcr.io/anomalyco/opencode

Mise​

mise use -g github:anomalyco/opencode

Mise manages OpenCode versions and makes it available globally.

Git Bash Support​

When using Git Bash on Windows, set the OPENCODE_GIT_BASH_PATH environment variable to enable proper shell integration:

# In PowerShell (System Properties or profile)
[System.Environment]::SetEnvironmentVariable(
  'OPENCODE_GIT_BASH_PATH',
  'C:\Program Files\Git\bin\bash.exe',
  'User'
)

Or set it per session:

$env:OPENCODE_GIT_BASH_PATH = "C:\Program Files\Git\bin\bash.exe"
opencode

This ensures OpenCode uses Git Bash for shell commands and terminal integration, providing better compatibility with Git-based workflows.

WSL Deep Dive​

Setting Up WSL for OpenCode​

# Install WSL with Ubuntu
wsl --install -d Ubuntu

# Set WSL 2 as default
wsl --set-default-version 2

# Access WSL filesystem
wsl

Inside WSL:

# Install OpenCode
curl -fsSL https://opencode.ai/install.sh | sh

# Verify installation
opencode --version

# Start in a project directory
cd /mnt/c/Users/YourName/Projects/my-app
opencode

Performance Considerations​

  • Project location: Store projects on the WSL filesystem (~/projects/) rather than /mnt/c/ for significantly better file I/O performance.
  • Cross-platform access: Access Windows files from WSL via /mnt/c/ — suitable for small projects or editing with Windows tools.
  • Node.js: Install Node.js inside WSL rather than using the Windows version for consistent behavior.

Path Translation​

When referencing Windows paths from WSL, use wslpath:

wslpath "C:\Users\YourName\Projects"   # Returns /mnt/c/Users/YourName/Projects
wslpath -w "/home/user/projects"        # Returns C:\Users\user\projects

Native Windows Limitations​

When running OpenCode directly on Windows (without WSL), be aware of:

  • Shell commands: Some Unix commands may not be available. Install Git Bash or use the Windows Subsystem for Linux.
  • File watching: Filesystem event handling differs from Linux. Performance may vary for large projects.
  • Terminal features: Some TUI features (true color, certain keybindings) may not work in older Windows terminals. Use Windows Terminal for the best experience.
  • LSP servers: Language servers expecting Unix paths may need configuration. Use WSL for development workflows.
  • Symlinks: Creating symlinks requires elevated permissions on Windows. Configure OpenCode to avoid symlink-dependent operations.

Environment Variables​

Configure OpenCode on Windows through environment variables:

# PowerShell profile ($PROFILE)
$env:ANTHROPIC_API_KEY = "sk-ant-..."
$env:OPENAI_API_KEY = "sk-proj-..."
$env:OPENCODE_GIT_BASH_PATH = "C:\Program Files\Git\bin\bash.exe"
$env:OPENCODE_SERVER_PASSWORD = "my-password"

For persistent settings, add these to your PowerShell profile ($PROFILE) or through System Environment Variables.

Chocolatey Package Management​

# Install
choco install opencode

# Upgrade
choco upgrade opencode

# Uninstall
choco uninstall opencode

Troubleshooting Windows-Specific Issues​

Terminal Rendering​

If the TUI displays incorrectly:

  1. Use Windows Terminal (recommended)
  2. Enable experimental.rendering.software in Windows Terminal settings for GPU rendering issues
  3. Ensure the terminal font supports Nerd Font icons (e.g., Cascadia Code PL, FiraCode Nerd Font)

Path Issues​

If OpenCode cannot find executables:

# Verify PATH
$env:PATH

# Add OpenCode to PATH (if not automatically added)
$env:PATH += ";$env:APPDATA\npm"
$env:PATH += ";$env:LOCALAPPDATA\Programs\opencode"

WSL Interop​

If OpenCode in WSL cannot access Windows files:

# Check if WSL interop is enabled
cat /proc/sys/fs/binfmt_misc/WSLInterop

# Mount Windows drives
ls /mnt/c/