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

- Author: azeru (https://wurk.fun/user/azeru)
- Published: 2026-08-14
- Updated: 2026-08-20
- Canonical (HTML): https://wurk.fun/blog/how-to-set-up-a-linux-development-environment-on-windows-using-wsl-2
- Cover image: https://ik.imagekit.io/wurk/IMG_0535_HCo_I0as1.jpeg

---

## 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:

```text
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.

![window](https://ik.imagekit.io/wurk/window_pkCbwrevm.png)

---

## Step 2: Install WSL

Run:

```powershell
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:

```powershell
wsl --install -d Debian
```

Microsoft supports installing a specific distribution with the `-d` option.

![wsl version](https://ik.imagekit.io/wurk/wsl_version_ZE-tNqcDQ.png)

---

# 4. Check Available Linux Distributions

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

```powershell
wsl --list --online
```

You can also use the shorter version:

```powershell
wsl -l -o
```

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

For this tutorial, we're using **Debian**.

![available distros](https://ik.imagekit.io/wurk/available_distros_Sb_BlvSdl.png)

---

# 5. Install Debian

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

```powershell
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:

```powershell
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:

```powershell
wsl -l -v
```

You should see something similar to:

```text
  NAME      STATE      VERSION
* Debian    Running    2
```

The distribution may say `Stopped` instead of `Running`. That's normal.

The important part is:

```text
VERSION
2
```

This confirms that Debian is running under WSL 2.

You can also check the overall WSL configuration with:

```powershell
wsl --status
```

And:

```powershell
wsl --version
```

![list available diiistros](https://ik.imagekit.io/wurk/list_available_diiistros_tv3UHvHdO.png)

---

# 7. Open Debian

Now open Debian from the Start menu.

Alternatively, from PowerShell:

```powershell
wsl
```

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

Inside Debian, verify the operating system:

```bash
cat /etc/os-release
```

Then check the Linux kernel:

```bash
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:

```bash
sudo apt update
```

Then upgrade the installed packages:

```bash
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.

![uprade](https://ik.imagekit.io/wurk/uprade_I0TqUgHtN.png)

---

# 9. Install Essential Development Tools

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

```bash
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:

```bash
git --version
```

```bash
curl --version
```

```bash
gcc --version
```

![evidence of installation](https://ik.imagekit.io/wurk/evidence_of_installation_7sPyzxLV9.png)

---

# 10. Configure Git

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

Run:

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

Replace `"Your Name"` with the name you want associated with your commits.

Then:

```bash
git config --global user.email "your-email@example.com"
```

Use the email associated with your Git account if appropriate.

Check the configuration:

```bash
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:

```bash
mkdir -p ~/projects
```

Then enter it:

```bash
cd ~/projects
```

Check your current location:

```bash
pwd
```

You should get something similar to:

```text
/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:

```text
/home/username
```

Windows drives are available through `/mnt`.

For example:

```text
C:\Users\PC\Documents
```

can generally be accessed from WSL as:

```text
/mnt/c/Users/PC/Documents
```

You can navigate there with:

```bash
cd /mnt/c/Users/PC/Documents
```

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

For example:

```text
~/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:

```bash
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:

```bash
nvm install --lts
```

Then activate it:

```bash
nvm use --lts
```

Verify Node.js:

```bash
node --version
```

And npm:

```bash
npm --version
```

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

```bash
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:

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

Allow the installation to complete.

![install opencoe](https://ik.imagekit.io/wurk/install_opencoe_iWX2eqZhh.png)

---

# 16. Verify OpenCode

After installation, check the version:

```bash
opencode --version
```

Then check which executable your shell is using:

```bash
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:

```bash
which opencode
```

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

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

```text
/home/username/.opencode/bin/opencode
```

The exact path can vary.

![opencode check](https://ik.imagekit.io/wurk/opencode_check_7j0b7bK5n.png)

---

# 17. Create a Project Directory for OpenCode

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

From Debian:

```bash
mkdir -p ~/projects/opencode-test
```

Enter the directory:

```bash
cd ~/projects/opencode-test
```

Verify:

```bash
pwd
```

You should see something similar to:

```text
/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:

```bash
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.

![opencode tui](https://ik.imagekit.io/wurk/opencode_tui_NmmU9jq2RV.png)

![opencode tui](https://ik.imagekit.io/wurk/opencode_tui_lRVLLWfWG.png)

---

# 19. Initialize the Project

Inside OpenCode, run:

```text
/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:

```bash
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:

```bash
cd ~/projects
```

Clone a project:

```bash
git clone <repository-url>
```

Enter the project:

```bash
cd <project-directory>
```

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

```bash
npm install
```

Then follow the project's documentation to start it.

For many development projects, this might be:

```bash
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:

```powershell
wsl
```

You can also execute Linux commands from Windows:

```powershell
wsl pwd
```

And from inside WSL, you can access Windows files through `/mnt`.

For example:

```bash
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:

```text
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:

```powershell
wsl -l -v
```

If Debian shows version `1`, convert it to WSL 2:

```powershell
wsl --set-version Debian 2
```

Then verify again:

```powershell
wsl -l -v
```

You want Debian to show:

```text
VERSION
2
```

---

## Problem 2: A command isn't found

If you install a tool and the terminal says:

```text
command not found
```

don't immediately reinstall everything.

First check:

```bash
which <command>
```

Then inspect your PATH:

```bash
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:

```text
Windows environment ≠ WSL environment
```

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

```bash
which <command>
```

For OpenCode specifically:

```bash
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:

```text
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:

```powershell
wsl --status
```

Then:

```powershell
wsl -l -v
```

You should see Debian using WSL 2.



---

## From Debian

Run:

```bash
git --version
```

```bash
curl --version
```

```bash
gcc --version
```

```bash
nvm --version
```

```bash
node --version
```

```bash
npm --version
```

And finally:

```bash
opencode --version
```

You can also verify the OpenCode installation location:

```bash
which opencode
```



---

# 25. What We Have Built

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

```text
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:

```bash
which <command>
```

can help.

### Keep projects organized

A simple structure such as:

```text
~/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.**