How to Set Up a Linux Development Environment on Windows Using WSL 2

Introduction

Windows is a perfectly capable operating system for software development, but some development tools and workflows are designed with Linux in mind.

You don't necessarily need to replace Windows with Linux to get access to those tools.

Windows Subsystem for Linux (WSL) allows you to run a Linux distribution directly inside Windows. With WSL 2, you can work with a real Linux kernel while still keeping your normal Windows applications and workflow.

In this guide, I'll show you how to turn a Windows machine into a practical Linux development environment using WSL 2 and Debian.

We'll go beyond simply installing WSL. By the end, we'll have:

• WSL 2
• Debian
• Essential Linux development tools
• Git
• cURL
• Build tools
• NVM
• Node.js and npm
• OpenCode
• A dedicated project directory
• A working OpenCode project

The goal is simple: start with Windows and finish with a Linux development environment that you can actually build software with.

---

1. What You'll Need

Before starting, you'll need:

• Windows 10 or Windows 11
• An internet connection
• Administrator access to your Windows computer
• Enough storage for your Linux distribution and development projects

You don't need to:

• Dual-boot Windows and Linux
• Replace Windows
• Install a traditional virtual machine
• Rent a cloud server

WSL gives us a Linux environment while allowing Windows to remain our main operating system.

---

2. What Is WSL 2?

WSL stands for Windows Subsystem for Linux.

It allows Linux distributions such as Debian and Ubuntu to run inside Windows.

The basic setup looks like this:

Windows
   │
   └── WSL 2
        │
        └── Debian
             │
             ├── Git
             ├── Node.js
             ├── npm
             ├── OpenCode
             └── Your projects

WSL 2 is different from the original WSL 1 architecture. It uses a real Linux kernel and provides a much more complete Linux environment.

For developers, this means you can use Linux shells, package managers, development tools and command-line applications without leaving Windows.

---

3. Install WSL

Step 1: Open PowerShell as Administrator

Open the Windows Start menu and search for PowerShell.

Right-click it and select:

Run as administrator

You should see an administrator PowerShell window.

---

Step 2: Install WSL

Run:

wsl --install

On supported Windows versions, this command sets up the components required for WSL and installs the default Linux distribution.

Windows may ask you to restart your computer.

If you're following this guide specifically with Debian, you can install Debian directly with:

wsl --install -d Debian

Microsoft supports installing a specific distribution with the

-d

option.

---

4. Check Available Linux Distributions

If you want to see which distributions are available, run:

wsl --list --online

You can also use the shorter version:

wsl -l -o

You should see distributions such as Debian and Ubuntu in the list.

For this tutorial, we're using Debian.

---

5. Install Debian

If Debian wasn't installed during the initial WSL installation, run:

wsl --install -d Debian

Windows will download and install Debian.

After installation, launch Debian from the Windows Start menu.

You can also launch it from PowerShell with:

wsl -d Debian

The first time Debian starts, it will initialize the Linux environment and ask you to create a Linux username and password.

Your Linux username and password are separate from your Windows credentials.

When entering your Linux password, nothing will appear in the terminal while you type. This is normal.

---

6. Verify WSL 2

After Debian is installed, return to PowerShell and run:

wsl -l -v

You should see something similar to:

  NAME      STATE      VERSION
* Debian    Running    2

The distribution may say

Stopped

instead of

Running

. That's normal.

The important part is:

VERSION
2

This confirms that Debian is running under WSL 2.

You can also check the overall WSL configuration with:

wsl --status

And:

wsl --version

---

7. Open Debian

Now open Debian from the Start menu.

Alternatively, from PowerShell:

wsl

If Debian is your default distribution, this will open Debian directly.

Inside Debian, verify the operating system:

cat /etc/os-release

Then check the Linux kernel:

uname -r

At this point, you're no longer working in PowerShell. You're inside your Linux environment.

---

8. Update Debian

Before installing development tools, update the system's package information:

sudo apt update

Then upgrade the installed packages:

sudo apt upgrade -y

Why do this?

Linux distributions use package repositories to provide software.

apt update

refreshes the information about available packages.

apt upgrade

installs available updates for packages already installed.

It's a good first step when setting up a new development environment.

---

9. Install Essential Development Tools

Now install some basic tools that we'll use throughout the setup:

sudo apt install -y build-essential curl git unzip

This installs:

build-essential

A collection of common compilation and build tools.

curl

A command-line tool for transferring data. It's also commonly used by installation scripts.

git

The standard distributed version-control system used by most software development projects.

unzip

A command-line utility for working with ZIP archives.

Verify the installation:

git --version

curl --version

gcc --version

---

10. Configure Git

If you're going to work with Git repositories, configure your Git identity.

Run:

git config --global user.name "Your Name"

Replace

"Your Name"

with the name you want associated with your commits.

Then:

git config --global user.email "[email protected]"

Use the email associated with your Git account if appropriate.

Check the configuration:

git config --global --list

You should see your name and email in the output.

Tip: Don't put passwords, API keys or other secrets into screenshots.

---

11. Create a Development Workspace

I recommend keeping your Linux development projects in a dedicated directory.

Create one with:

mkdir -p ~/projects

Then enter it:

cd ~/projects

Check your current location:

pwd

You should get something similar to:

/home/username/projects

This directory will be our workspace for the rest of the tutorial.

---

12. Windows Files vs. Linux Files

One of the most important concepts to understand when using WSL is that you have access to both the Linux filesystem and your Windows drives.

Your Linux home directory looks like:

/home/username

Windows drives are available through

/mnt

.

For example:

C:\Users\PC\Documents

can generally be accessed from WSL as:

/mnt/c/Users/PC/Documents

You can navigate there with:

cd /mnt/c/Users/PC/Documents

However, for Linux-based development projects, keeping the repository inside the Linux filesystem can be preferable.

For example:

~/projects/my-project

The current OpenCode WSL documentation also recommends considering the WSL filesystem for repositories when performance matters.

This is particularly useful when working with projects containing large numbers of files such as

node_modules

.

---

13. Install NVM

If you're doing JavaScript or TypeScript development, managing Node.js versions becomes important.

Instead of installing one Node.js version globally and forgetting about it, we can use NVM — Node Version Manager.

NVM allows you to install and switch between Node.js versions.

Install NVM using its current official installation instructions.

After installation, restart your terminal or reload your shell configuration as instructed by NVM.

Then verify:

nvm --version

You should receive an NVM version number.

---

14. Install Node.js and npm

Now install the current Long Term Support version of Node.js through NVM:

nvm install --lts

Then activate it:

nvm use --lts

Verify Node.js:

node --version

And npm:

npm --version

You can also see the Node versions managed by NVM with:

nvm ls

At this point, your Debian environment can run JavaScript and TypeScript projects independently of any Node.js installation you might have on Windows.

---

15. Install OpenCode Inside WSL

Now we'll add an optional developer tool to the environment: OpenCode.

OpenCode can run directly on Windows, but its current documentation recommends using WSL on Windows for the best experience, citing filesystem performance, terminal support and compatibility with development tools.

The important part is that we're going to install OpenCode inside Debian, not in PowerShell.

Make sure you're looking at a Debian terminal.

Then run:

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

Allow the installation to complete.

---

16. Verify OpenCode

After installation, check the version:

opencode --version

Then check which executable your shell is using:

which opencode

The second command is important.

When you have both Windows and Linux environments, it's easy to accidentally install a tool in one environment and then try to use it from the other.

Running:

which opencode

helps you confirm which executable your Debian environment is actually using.

A path inside your Linux home directory may look similar to:

/home/username/.opencode/bin/opencode

The exact path can vary.

---

17. Create a Project Directory for OpenCode

Now let's test the development environment with an actual project directory.

From Debian:

mkdir -p ~/projects/opencode-test

Enter the directory:

cd ~/projects/opencode-test

Verify:

pwd

You should see something similar to:

/home/username/projects/opencode-test

This is important because OpenCode will work relative to the project you're currently inside.

---

18. Launch OpenCode

From inside the project directory, run:

opencode

OpenCode should start in your terminal.

We're intentionally launching it from inside WSL rather than from PowerShell.

This keeps the development tooling and project environment inside the same Linux environment.

---

19. Initialize the Project

Inside OpenCode, run:

/init

This allows OpenCode to analyze the project and create project-specific instructions.

For an empty project, there won't be much to analyze yet, but this establishes the project's OpenCode configuration.

Depending on the current OpenCode version and project state, this can create an

AGENTS.md

file.

You can verify the project directory from Debian after exiting OpenCode:

ls -la

If

AGENTS.md

was created, it should appear in the project directory.

OpenCode's documentation describes

AGENTS.md

as a way of giving the agent project-specific instructions and recommends keeping it with the project when appropriate.

---

20. Run a Real Project

Now that the environment is ready, test it with a real repository.

For example:

cd ~/projects

Clone a project:

git clone <repository-url>

Enter the project:

cd <project-directory>

If it's a Node.js project, install its dependencies:

npm install

Then follow the project's documentation to start it.

For many development projects, this might be:

npm run dev

The exact command depends on the project.

The point of this step isn't the particular application.

It's proving that your environment can actually:

• Clone repositories
• Run Git
• Run Node.js
• Install npm dependencies
• Run development commands
• Use OpenCode inside the project

---

21. Using Windows and WSL Together

WSL doesn't mean you have to stop using Windows.

You can launch WSL from PowerShell:

wsl

You can also execute Linux commands from Windows:

wsl pwd

And from inside WSL, you can access Windows files through

/mnt

.

For example:

cd /mnt/c/Users/PC/Documents

OpenCode's current WSL documentation also supports working with Windows-hosted project files through

/mnt/c/

,

/mnt/d/

, and similar paths.

For development projects, however, keeping the repository under your Linux home directory is often the cleaner option.

---

22. A Useful Windows + WSL Workflow

After everything is installed, your workflow can look like this:

Windows
   │
   ├── Browser
   ├── VS Code
   └── Other Windows applications
          │
          │
          ▼
       WSL 2
          │
          ▼
       Debian
          │
          ├── Git
          ├── NVM
          ├── Node.js
          ├── npm
          ├── OpenCode
          │
          └── ~/projects
                 │
                 ├── project-1
                 ├── project-2
                 └── project-3

This gives you the convenience of Windows while keeping your development environment Linux-based.

---

23. Common Problems

Problem 1: Debian is using WSL 1

Check:

wsl -l -v

If Debian shows version

1

, convert it to WSL 2:

wsl --set-version Debian 2

Then verify again:

wsl -l -v

You want Debian to show:

VERSION
2

---

Problem 2: A command isn't found

If you install a tool and the terminal says:

command not found

don't immediately reinstall everything.

First check:

which <command>

Then inspect your PATH:

echo $PATH

If you've just installed something that modifies your shell configuration, restart the terminal and try again.

---

Problem 3: You accidentally installed the Windows version of a tool

This is one of the easiest mistakes to make when using Windows and WSL together.

Remember:

Windows environment ≠ WSL environment

If you're inside Debian, check where the command comes from:

which <command>

For OpenCode specifically:

which opencode

This can help identify whether you're using the Linux installation you intended.

The safest approach is to decide which environment should own the tool and install it there rather than maintaining unnecessary duplicate installations.

---

Problem 4: Your project is slow

If you're working with a large development project, consider where the repository is stored.

For example:

Windows filesystem:
 /mnt/c/Users/PC/project

Linux filesystem:
 ~/projects/project

For Linux-based development workloads, keeping the project inside the WSL filesystem can provide a smoother experience.

This is also the approach currently recommended by OpenCode's WSL guidance when performance matters.

---

24. Final Verification

At this point, let's verify the complete environment.

From Windows

Run:

wsl --status

Then:

wsl -l -v

You should see Debian using WSL 2.

---

From Debian

Run:

git --version

curl --version

gcc --version

nvm --version

node --version

npm --version

And finally:

opencode --version

You can also verify the OpenCode installation location:

which opencode

---

25. What We Have Built

Starting with a normal Windows installation, we've created:

Windows
    │
    ▼
WSL 2
    │
    ▼
Debian
    │
    ├── Git
    ├── cURL
    ├── Build tools
    ├── NVM
    ├── Node.js
    ├── npm
    │
    └── OpenCode
          │
          ▼
      Development
       Projects

This isn't a replacement for Windows.

It's a Linux development environment running alongside it.

You can continue using Windows applications normally while using Debian for development tasks that benefit from Linux tooling.

---

26. Final Tips

Don't blindly copy commands

Commands are useful, but understanding what they do will make troubleshooting much easier.

Know which environment you're in

Before installing or running a tool, ask:

"Am I in Windows or WSL?"

If you're unsure, commands such as:

which <command>

can help.

Keep projects organized

A simple structure such as:

~/projects/

makes it easier to manage multiple repositories.

Use version managers where appropriate

NVM makes it much easier to work with projects that require different Node.js versions.

Don't reinstall everything when something breaks

Check the actual error first.

Look at:

• The command output
• The executable location
• Your PATH
• Your current environment
• The project's required versions

A systematic debugging process is usually faster than repeatedly reinstalling software.

---

Conclusion

Setting up Linux development tools on Windows doesn't require giving up Windows itself.

With WSL 2 and Debian, you can build a Linux-based development environment that lives alongside your normal Windows workflow.

We started with WSL, installed Debian, configured the Linux environment, installed essential development tools, added Git and Node.js, and finally installed OpenCode directly inside WSL and tested it from an actual project directory.

The final environment gives you a practical foundation for building software while keeping Windows available for everything else.

The most important thing to take away isn't a specific command.

It's understanding the relationship between Windows, WSL, Debian and your development tools.

Once that makes sense, you can install and manage much more sophisticated development tooling without constantly wondering whether you're running the Windows version or the Linux version.

Your Windows machine can be both your everyday computer and your Linux development workstation.