How to Install WSL for Vibe Coding on Windows

Many modern development tools assume that you are working in a Linux or Unix-style environment. Their installation guides may use commands such as ls, cd, mkdir, and sudo, even when the reader is using a Windows computer.

Windows Subsystem for Linux, usually called WSL, helps bridge that gap. It allows you to run a Linux environment alongside Windows without replacing Windows or setting up a traditional virtual machine manually.

For vibe coding, WSL can be especially useful when working with terminal-based tools, package managers, web development frameworks, deployment scripts, and coding agents designed around Linux-style workflows.

This guide explains what WSL does, when it is useful, how to install it, and how to verify that your Linux environment is ready.

Version note: Windows requirements, installation screens, and WSL commands can change. Before publishing or following this guide in a production environment, compare the version-sensitive steps with the current official Microsoft WSL documentation.

• Previous article: How to Install and Set Up Visual Studio Code for Vibe Coding

What You Will Learn

By the end of this guide, you should be able to:

• explain what WSL is and why developers use it;
• check whether your Windows system can use WSL;
• install WSL from an elevated PowerShell window;
• install and open a Linux distribution;
• create a Linux username and password;
• verify the installed WSL version and distribution;
• update the Linux package list;
• recognize common setup problems.

This article focuses on installing and verifying WSL. Connecting WSL to Visual Studio Code will be covered in the next guide.

What WSL Does

WSL gives Windows users access to a Linux environment from the same computer.

You continue using Windows normally. Your browser, desktop applications, documents, and Windows settings remain available. WSL adds a Linux terminal and Linux file system that can run alongside them.

This is different from replacing Windows with Linux.

It is also different from opening a Linux website or using a remote server. The Linux environment runs locally on your Windows computer.

A simplified view looks like this:

Windows
├── Browser
├── Visual Studio Code
├── Windows applications
└── WSL
    ├── Linux terminal
    ├── Linux home directory
    ├── Linux commands
    └── Development tools

WSL supports Linux distributions such as Ubuntu and others made available through Microsoft’s supported installation channels.

A Linux distribution provides the user-space tools, package manager, shell, and file structure you interact with. In this series, Ubuntu is a practical beginner choice because it is widely documented and commonly used in development tutorials.

Why WSL Is Useful for Vibe Coding

You can write code on Windows without WSL. PowerShell, the Windows command prompt, and native Windows development tools are sufficient for many projects.

WSL becomes useful when your development workflow depends on tools or instructions written for Linux.

Examples include:

• terminal-based coding assistants;
• shell scripts;
• Node.js, Python, and web development tools;
• Linux package managers;
• deployment environments based on Linux;
• Docker-related workflows;
• tutorials that assume a Bash shell;
• development servers that will later run on Linux.

A major advantage is consistency.

Suppose you build a web application on Windows but deploy it to a Linux server. Differences in file paths, command syntax, permissions, and shell behavior can create problems. Working inside WSL can reduce some of those differences because your local development environment is already Linux-based.

That does not mean WSL makes every environment identical. Production servers still have their own configuration, security rules, software versions, and deployment requirements. WSL simply gives you a more Linux-compatible local workflow.

When You May Not Need WSL

WSL is not mandatory for every Windows developer.

You may not need it when:

• the software you use has full native Windows support;
• your project is designed specifically for Windows;
• your team uses PowerShell-based scripts;
• you are learning a tool that works entirely inside the browser;
• adding another environment would create more confusion than value.

The goal is not to install WSL because other developers use it. The goal is to choose an environment that matches the tools and projects you plan to use.

For this series, WSL provides a consistent environment for terminal-based development and later Claude Code exercises.

Check Your Windows Environment

Before installing WSL, confirm that you are using a currently supported edition of Windows 10 or Windows 11.

You can check your Windows version by pressing the Windows key, typing:

winver

Then open the result.

A small window should display your Windows edition, version, and operating system build.

The simplified wsl --install workflow has historically required a sufficiently recent Windows 10 build or Windows 11. Because Microsoft may update these requirements, verify the current minimum version in the official WSL installation documentation before publication.

You should also install pending Windows updates before setting up WSL. System updates may include components required by virtualization and WSL.

Check Whether Virtualization Is Available

WSL 2 uses virtualization technology.

To check its status:

1. Open Task Manager.
2. Select the Performance section.
3. Open the CPU view.
4. Look for a virtualization status entry.

If virtualization is shown as enabled, you can continue.

If it is disabled, the setting may need to be enabled in your computer’s BIOS or UEFI firmware. The exact process depends on the device manufacturer.

Do not change unfamiliar firmware settings at random. Look for documentation specific to your computer model or motherboard.

On a work-managed computer, virtualization or WSL may be controlled by an administrator. In that case, contact the appropriate IT team rather than trying to bypass organizational restrictions.

Install WSL from PowerShell

The standard installation process begins in Windows PowerShell with administrator privileges.

Open PowerShell as an Administrator

1. Open the Windows Start menu.
2. Search for PowerShell.
3. Right-click Windows PowerShell or the current PowerShell application.
4. Choose Run as administrator.
5. Approve the Windows security prompt.

The title bar should indicate that the window has administrative privileges.

Run the following command:

wsl --install

This command asks Windows to install the WSL components and a default Linux distribution when supported by the current installation method.

The command may:

• enable required Windows features;
• install or update WSL components;
• download a default Linux distribution;
• ask you to restart Windows.

Read the output rather than closing the window immediately.

If Windows asks for a restart, save your work in other applications and restart the computer.

Why Administrator Access Is Needed

The initial setup can enable operating-system features. Standard user permissions are not always sufficient for that task.

After WSL is installed, you normally do not need an elevated PowerShell window every time you open your Linux environment.

Using administrator privileges only when required is a good security habit. A terminal with elevated permissions can make system-level changes, so commands should be reviewed before execution.

Choose a Linux Distribution

The default wsl --install command may install Ubuntu automatically, depending on the current Windows and WSL behavior.

To see the distributions currently available for online installation, use:

wsl --list --online

A successful result should display a list of distribution names recognized by WSL.

To install a specific distribution, the current syntax generally follows this pattern:

wsl --install -d Ubuntu

The exact distribution names shown by wsl --list --online should be used rather than guessed.

For a beginner following this series, Ubuntu is a reasonable choice because:

• it has extensive documentation;
• many development tutorials use it;
• common tools provide Ubuntu instructions;
• its package management workflow is widely understood.

You do not need multiple Linux distributions for the beginner workflow. Installing several distributions at once can make it harder to remember where files and tools were configured.

Start with one distribution and add another only when a project gives you a clear reason.

Complete the First Linux Setup

After installation and any required restart, open the installed Linux distribution from the Windows Start menu.

The first launch may take longer than later launches because the distribution needs to complete its initial setup.

You should eventually be asked to create:

• a Linux username;
• a Linux password.

These credentials belong to the Linux environment. They do not have to match your Windows username or password.

Choose a Linux Username

Use a simple username containing lowercase letters and, when needed, numbers.

For example:

alex

Avoid spaces and complicated punctuation.

This username becomes part of your Linux home-directory path, which may look like:

/home/alex

Create a Linux Password

When the terminal asks for a password, type it and press Enter.

Linux terminals commonly do not display dots, asterisks, or other characters while you type a password. The screen may appear unchanged even though the password is being entered.

This behavior is normal.

Choose a password you can remember, because it may be requested when using administrative commands inside Linux.

The Linux password is used with tools such as sudo, which allows an approved command to run with elevated Linux privileges.

Do not confuse the Linux sudo password with:

• your Windows password;
• your Microsoft account password;
• your GitHub password;
• an API key;
• an AI tool account credential.

Verify That WSL Is Running

After the Linux terminal opens, look at the prompt.

It may contain your Linux username and computer name, followed by a symbol such as $.

Run:

pwd

This prints the current working directory.

On a new installation, the result will usually be your Linux home directory:

/home/your-username

Next, run:

uname -a

This displays information about the Linux kernel and environment.

The exact output differs by WSL version and system, but it should confirm that you are inside a Linux environment.

You can also list the files in the current directory:

ls

A new home directory may contain only a few items or appear empty.

Verify WSL from PowerShell

Return to a regular Windows PowerShell window and run:

wsl --status

This should display general WSL configuration information when the command is supported by the installed version.

Then run:

wsl --list --verbose

The shorter equivalent is commonly:

wsl -l -v

This command lists installed distributions and normally shows:

• the distribution name;
• whether it is running or stopped;
• the WSL version assigned to it.

For the workflow in this series, WSL 2 is generally the preferred version because it provides broader Linux compatibility than the original architecture.

If your installed distribution is shown as version 2, the main installation is complete.

Update WSL and Linux Packages

WSL itself and the Linux distribution contain separate components.

From Windows PowerShell, the following command can update the WSL package when supported:

wsl --update

Read the output to confirm whether an update was installed or whether WSL was already current.

Inside Ubuntu, update the package index with:

sudo apt update

You may be asked for the Linux password you created earlier.

This command refreshes information about the software packages available from the configured Ubuntu repositories. It does not necessarily upgrade every installed package.

A successful command ends without a fatal error and displays package repository information.

To install currently available package upgrades, Ubuntu users commonly run:

sudo apt upgrade

Read the proposed changes before confirming.

For a brand-new environment, updating the package list is a useful first step. In professional or production environments, package upgrades should be planned because newer versions can affect existing applications.

Understand the WSL File Systems

Windows and WSL can access each other’s files, but they use different path formats.

A Windows path may look like:

C:\Users\Alex\Documents

Inside WSL, the same Windows drive is commonly available under a mount path such as:

/mnt/c/Users/Alex/Documents

The Linux home directory is different:

/home/alex

For tools running primarily inside WSL, keeping project files inside the Linux file system is often the more consistent approach.

For example:

/home/alex/projects

This can reduce performance and file-watching issues that sometimes occur when Linux tools repeatedly access files stored on a mounted Windows drive.

The next article will establish a clear folder strategy and show how to open a WSL project in VS Code.

For now, do not move important projects between file systems without understanding the paths. Create a small test folder inside your Linux home directory instead.

Run:

mkdir -p ~/projects

This command creates a projects directory inside your Linux home folder.

The -p option tells mkdir to create the required directory structure without failing if the directory already exists.

Move into it:

cd ~/projects

Confirm your location:

pwd

The result should look similar to:

/home/your-username/projects

This folder will be useful in the next guide.

Useful WSL Management Commands

The following commands are run from Windows PowerShell, not from inside the Linux terminal.

List Installed Distributions

wsl --list --verbose

Use this to confirm which distributions are installed and whether they use WSL 1 or WSL 2.

Stop All Running WSL Distributions

wsl --shutdown

This stops all running WSL environments.

It can be useful after configuration changes or when troubleshooting a WSL process that is no longer responding.

Do not use it while an important command, database, development server, or file operation is still running inside WSL.

Start the Default Distribution

wsl

This opens the default installed Linux distribution in the current terminal window.

Open a Specific Distribution

Use the exact name displayed by the list command:

wsl -d Ubuntu

This is useful when more than one distribution is installed.

Beginners should avoid commands that unregister or delete a distribution unless they fully understand the consequences. Removing a distribution can delete its Linux files and installed tools.

Common WSL Installation Problems

The wsl Command Is Not Recognized

If PowerShell reports that wsl is not recognized, check:

• whether Windows is fully updated;
• whether your Windows version supports the current WSL installation method;
• whether you opened Windows PowerShell rather than a Linux terminal;
• whether the required Windows features are available;
• whether the computer is managed by an organization.

Restart Windows after installing pending updates and check the current official manual installation instructions if the simplified command is not supported.

The Installation Requires a Restart

This is expected when Windows enables required system features.

Save open work, restart the computer, and then open the Linux distribution again.

Virtualization Is Disabled

WSL 2 may fail when hardware virtualization is disabled.

Check Task Manager and your device documentation. On organization-managed hardware, ask the administrator responsible for the device.

Do not download unofficial utilities that claim to modify firmware settings automatically.

The Linux Terminal Closes Immediately

Open the distribution again from the Start menu and watch for an error message.

Also check the installed state from PowerShell:

wsl --list --verbose

If the distribution is partially installed, compare the error with the current Microsoft troubleshooting documentation before reinstalling or deleting anything.

The Password Appears Not to Work

Remember that Linux does not display password characters while you type.

Enter the password carefully and press Enter.

If the password was forgotten, follow the current official password-reset process for WSL. Do not remove the distribution as a first troubleshooting step, because that may destroy its files.

A Command Works in PowerShell but Not in Linux

PowerShell and Linux use different shells and command sets.

For example:

Get-Location

is a PowerShell command, while:

pwd

is a Linux shell command.

Some commands share the same name but behave differently.

Always check which terminal is active before running instructions from a tutorial.

You Installed More Than One Distribution

Run:

wsl --list --verbose

Identify which distribution you intend to use.

You can specify it when launching WSL:

wsl -d Ubuntu

Do not delete the other distribution until you confirm that it contains no files or tools you need.

Practical Advice for a Clean WSL Setup

The main source of beginner confusion is often not the installation itself. It is losing track of which environment is active.

Before running a command, identify three things:

1. Which terminal am I using?
2. Which directory am I in?
3. Which operating-system environment owns the files?

Inside Linux, use:

pwd

In Windows PowerShell, use:

Get-Location

Also pay attention to path styles.

A path beginning with /home/ is in the Linux file system. A path beginning with C:\ is a Windows path. A path beginning with /mnt/c/ is WSL accessing the Windows C drive.

In software projects, consistency is usually more valuable than cleverness. Choose one primary project location and use it deliberately.

For the WSL-based workflow in this series, we will keep Linux-oriented development projects under:

~/projects

This makes it easier to know where commands should run and reduces accidental mixing between Windows and Linux tools.

Verify Your WSL Setup

Before moving to the next article, confirm the following:

• Windows is updated.
• Virtualization is enabled or available.
• wsl --install completed successfully.
• A Linux distribution is installed.
• You created a Linux username and password.
• The Linux terminal opens.
• pwd displays a Linux path.
• uname -a returns Linux environment information.
• wsl --list --verbose displays your distribution.
• The distribution uses WSL 2 for this workflow.
• sudo apt update completes without a fatal error.
• The ~/projects directory exists.

A simple final check inside Ubuntu is:

cd ~/projects
pwd

The result should resemble:

/home/your-username/projects

If this works, your WSL environment is ready for the next stage.

Conclusion

WSL gives Windows users a practical Linux environment without requiring them to replace Windows.

It is useful for development tools, terminal workflows, package managers, and AI coding agents that are designed around Linux-style environments. It also helps reduce some differences between local development and Linux-based deployment environments.

The essential setup is straightforward: confirm Windows support, install WSL from an elevated PowerShell window, complete the Linux user setup, verify the distribution, and create a consistent project location.

The most important habit is knowing which environment and file system you are using. That awareness prevents many command, path, and configuration problems later.

In the next article, we will connect Visual Studio Code to WSL, open the ~/projects directory as a Linux-based workspace, and verify that the VS Code terminal is running inside the correct environment.

Frequently Asked Questions

Does WSL replace Windows?

No. WSL runs alongside Windows.

You continue using normal Windows applications while gaining access to a Linux terminal and file system. Removing or stopping WSL does not replace the Windows operating system.

Should I choose WSL 1 or WSL 2?

For the web development and AI-assisted workflows in this series, WSL 2 is generally the better fit because it provides broader Linux compatibility.

Some specialized networking, storage, or organization-managed environments may have different requirements. Check the current Microsoft comparison before choosing for a professional system.

Where should I store my coding projects?

For tools that run mainly inside WSL, storing projects in the Linux file system is often the most consistent option.

A simple location is:

/home/your-username/projects

The next guide will show how to open that folder directly in Visual Studio Code.

• Next article: How to Use Visual Studio Code with WSL