DEV Community

Arpan Dhara
Arpan Dhara

Posted on

🐧 WSL (Windows Subsystem for Linux) — Complete Setup & Command Guide

#linux #tools #tutorial

🚀 A step-by-step guide to installing, configuring, and using Windows Subsystem for Linux (WSL) — including essential commands, Windows/Linux integration, and useful advanced features.

📚 Table of Contents

🐧 What is WSL?

Windows Subsystem for Linux (WSL) allows you to run a Linux environment directly on Windows without needing to set up a traditional dual-boot system or a separate full virtual machine.

With WSL, you can:

  • 🐧 Run Linux distributions such as Ubuntu or Kali Linux.
  • 💻 Use Linux commands directly from Windows.
  • 🪟 Run Windows commands and applications from Linux.
  • 📁 Access Windows files from Linux.
  • 🛠️ Use development tools such as VS Code with a Linux environment.
  • 🔄 Move between Windows and Linux workflows easily.

This guide is based on the commands and workflow in the accompanying WSL notes, expanded into a beginner-friendly Dev.to tutorial.

⚙️ Step 1 — Enable WSL Features

Before using WSL, make sure the required Windows features are enabled.

1. Open Windows Features

On Windows:

  1. Press Win + R.
  2. Type: 
optionalfeatures
Enter fullscreen mode Exit fullscreen mode
  1. Press Enter.
  2. In Turn Windows features on or off, enable:
  • ✅ Virtual Machine Platform
  • ✅ Windows Subsystem for Linux
  1. Click OK.
  2. Restart your PC when Windows asks you to.

💡 Why are these features required?

Windows Subsystem for Linux provides the Windows component required to run Linux environments.

Virtual Machine Platform provides virtualization support used by WSL 2.

🔁 A restart is important after enabling these Windows features.

🔍 Step 2 — Check Your WSL Installation

Open PowerShell or Windows Terminal and run:

wsl --status
Enter fullscreen mode Exit fullscreen mode

What does it do?

wsl --status displays information about your WSL installation and configuration.

It is useful when you want to quickly check whether WSL is installed and see relevant version/configuration information.

Example 

wsl --status
Enter fullscreen mode Exit fullscreen mode

If WSL is working correctly, Windows will display information about the current WSL configuration.

🔄 Step 3 — Update WSL

To update WSL to the latest available version, run:

wsl --update
Enter fullscreen mode Exit fullscreen mode

What does it do?

The command checks for and installs available updates for WSL.

Recommended workflow

If you are setting up WSL on a new machine, it is a good idea to update WSL before continuing:

wsl --update
Enter fullscreen mode Exit fullscreen mode

📦 Step 4 — List Installed Linux Distributions

To see Linux distributions installed on your Windows system:

wsl --list
Enter fullscreen mode Exit fullscreen mode

You may also use:

wsl -l
Enter fullscreen mode Exit fullscreen mode

What does it do?

It lists the Linux distributions currently installed under WSL.

For example, you might have:

Ubuntu
kali-linux
Enter fullscreen mode Exit fullscreen mode

🟢 Show Currently Running Distributions

Use:

wsl --list --running
Enter fullscreen mode Exit fullscreen mode

or:

wsl -l --running
Enter fullscreen mode Exit fullscreen mode

What does it do?

This shows only the Linux distributions that are currently running.

This is useful when you have several distributions installed and want to know which ones currently have active WSL instances.

🔎 Show Detailed Distribution Information

Use:

wsl --list --verbose
Enter fullscreen mode Exit fullscreen mode

or:

wsl -l -v
Enter fullscreen mode Exit fullscreen mode

What does it show?

The verbose list provides additional information about installed distributions, including their WSL version and whether they are currently running.

This is particularly useful for checking whether a distribution is using WSL 1 or WSL 2.

🌐 Step 5 — See Available Distributions

To see Linux distributions that can be installed through WSL, run:

wsl --install --online
Enter fullscreen mode Exit fullscreen mode

You may also use:

wsl --list --online
Enter fullscreen mode Exit fullscreen mode

Depending on your Windows/WSL version, the output will show distributions available for installation.

💡 Why use this command?

Instead of guessing distribution names, you can first check the names Windows recognizes.

For example, a distribution may have a specific identifier that should be passed to the installation command.

📥 Step 6 — Install a Linux Distribution

Once you know the distribution name, install it with:

wsl --install -d <distribution-name>
Enter fullscreen mode Exit fullscreen mode

For example:

wsl --install -d Ubuntu
Enter fullscreen mode Exit fullscreen mode

Or, if the available distribution is listed under another identifier:

wsl --install -d kali-linux
Enter fullscreen mode Exit fullscreen mode

⚠️ Administrator privileges

The setup notes recommend running PowerShell as an Administrator for the installation process.

To do that:

  1. Open the Start menu.
  2. Search for PowerShell.
  3. Right-click PowerShell.
  4. Select Run as administrator.
  5. Run the WSL installation command.

🗑️ Step 7 — Uninstall a Distribution

There are two approaches mentioned in the notes.

Method 1 — Windows Settings

You can uninstall a Linux distribution through:

Settings → Apps → Installed apps
Enter fullscreen mode Exit fullscreen mode

Find the distribution you want to remove and uninstall it.

Method 2 — Use the WSL Command

You can unregister a distribution with:

wsl --unregister <distribution-name>
Enter fullscreen mode Exit fullscreen mode

Example:

wsl --unregister Ubuntu
Enter fullscreen mode Exit fullscreen mode

⚠️ Important

wsl --unregister removes the WSL distribution and its associated Linux filesystem/data.

Therefore, do not use this command unless you are sure you want to remove that distribution and its data.

⭐ Step 8 — Change the Default Distribution

If you have multiple Linux distributions installed, you can choose which one launches when you run:

wsl
Enter fullscreen mode Exit fullscreen mode

Use:

wsl --set-default <distribution-name>
Enter fullscreen mode Exit fullscreen mode

For example:

wsl --set-default kali-linux
Enter fullscreen mode Exit fullscreen mode

🧠 How does this work?

Suppose you have:

Ubuntu
kali-linux
Enter fullscreen mode Exit fullscreen mode

If Ubuntu is the default, running:

wsl
Enter fullscreen mode Exit fullscreen mode

opens Ubuntu.

If you change the default:

wsl --set-default kali-linux
Enter fullscreen mode Exit fullscreen mode

then:

wsl
Enter fullscreen mode Exit fullscreen mode

will open Kali Linux instead.

🚀 Step 9 — Launch and Switch Between Linux Distributions

Launch the default distribution

Simply run:

wsl
Enter fullscreen mode Exit fullscreen mode

This launches your default WSL distribution.

Launch a specific distribution

Use:

wsl -d <distribution-name>
Enter fullscreen mode Exit fullscreen mode

Example:

wsl -d Ubuntu
Enter fullscreen mode Exit fullscreen mode

or:

wsl -d kali-linux
Enter fullscreen mode Exit fullscreen mode

💡 Why is this useful?

You can keep multiple distributions installed and launch the one you need without changing the default distribution.

🚪 Step 10 — Exit and Shut Down WSL

Exit the current Linux shell

Inside Linux, run:

exit
Enter fullscreen mode Exit fullscreen mode

This exits the current Linux shell and returns you to the Windows terminal.

💡 The command exits the current shell; it does not necessarily mean every WSL distribution on your system has been shut down.

🛑 Shut down all WSL instances

From Windows, run:

wsl --shutdown
Enter fullscreen mode Exit fullscreen mode

What does it do?

It shuts down all currently running WSL distributions.

This can be useful when:

  • 🔄 You need to restart WSL completely.
  • 🧹 You want to release resources.
  • 🛠️ You are troubleshooting WSL behavior.

🎯 Shut down a specific distribution

Use:

wsl --terminate <distribution-name>
Enter fullscreen mode Exit fullscreen mode

Example:

wsl --terminate Ubuntu
Enter fullscreen mode Exit fullscreen mode

Difference between the two

Command Purpose
wsl --shutdown Stops all running WSL distributions
wsl --terminate Ubuntu Stops only the specified distribution

📁 Step 11 — Access Windows Drives from Linux

Windows drives are available inside Linux through /mnt.

For example, the Windows C: drive can be accessed as:

/mnt/c
Enter fullscreen mode Exit fullscreen mode

The D: drive can be accessed as:

/mnt/d
Enter fullscreen mode Exit fullscreen mode

You can navigate to a Windows drive with:

cd /mnt/c
Enter fullscreen mode Exit fullscreen mode

Example 

cd /mnt/c
ls
Enter fullscreen mode Exit fullscreen mode

This lets you view files and folders on the Windows C: drive from Linux.

🧠 Understanding the Path

Windows:

C:\
Enter fullscreen mode Exit fullscreen mode

WSL/Linux:

/mnt/c
Enter fullscreen mode Exit fullscreen mode

Windows:

D:\
Enter fullscreen mode Exit fullscreen mode

WSL/Linux:

/mnt/d
Enter fullscreen mode Exit fullscreen mode

The drive letter is converted into a Linux-style path under /mnt.

🪟 Step 12 — Use Windows Commands from Linux

One of the most useful WSL features is the ability to execute Windows commands directly from your Linux shell.

The notes demonstrate this by adding .exe to Windows commands.

For example:

ifconfig.exe
Enter fullscreen mode Exit fullscreen mode

or:

ping.exe
Enter fullscreen mode Exit fullscreen mode

The Windows executable is launched from the Linux environment.

🧠 The basic idea

Instead of:

Windows command
Enter fullscreen mode Exit fullscreen mode

you can invoke the Windows executable:

Windows command.exe
Enter fullscreen mode Exit fullscreen mode

This creates a convenient bridge between Linux and Windows.

📝 Step 13 — Run Windows Applications from Linux

WSL can also launch Windows applications.

For example, the notes use Windows Notepad:

notepad.exe document.txt
Enter fullscreen mode Exit fullscreen mode

This launches Notepad and opens the specified file.

Why is this useful?

You can combine:

  • 🐧 Linux command-line tools
  • 🪟 Windows desktop applications

in the same workflow.

For example:

notepad.exe document.txt
Enter fullscreen mode Exit fullscreen mode

allows a Windows GUI application to be launched directly from your Linux terminal.

💻 Step 14 — Use VS Code with WSL

WSL can be integrated with Visual Studio Code.

The notes describe the workflow as:

code demo.py
Enter fullscreen mode Exit fullscreen mode

This allows you to open a file from the Linux environment in VS Code.

Recommended setup

  1. Install Visual Studio Code on Windows.
  2. Install the WSL extension in VS Code.
  3. Open your WSL terminal.
  4. Navigate to your project.
  5. Run: 
code demo.py
Enter fullscreen mode Exit fullscreen mode

🧠 Why the WSL extension matters

The WSL integration allows VS Code to work with your Linux environment rather than treating the project as an ordinary Windows-only project.

This is especially useful for software development because you can use Linux tooling while keeping the Windows VS Code interface.

📂 Step 15 — Open the Current Linux Directory in Windows Explorer

From inside your Linux terminal, run:

explorer.exe .
Enter fullscreen mode Exit fullscreen mode

What does . mean?

In Linux:

.
Enter fullscreen mode Exit fullscreen mode

means:

the current directory

Therefore:

explorer.exe .
Enter fullscreen mode Exit fullscreen mode

means:

Open the current Linux directory using Windows Explorer.

Example 

cd ~/projects
explorer.exe .
Enter fullscreen mode Exit fullscreen mode

Windows Explorer will open the current location.

🐧 Step 16 — Run Linux Commands from Windows

WSL also works in the opposite direction.

You can execute Linux commands directly from a Windows terminal by prefixing the command with:

wsl
Enter fullscreen mode Exit fullscreen mode

For example:

wsl cat demo.txt
Enter fullscreen mode Exit fullscreen mode

How does it work?

Windows runs:

wsl
Enter fullscreen mode Exit fullscreen mode

and passes the remaining command to the Linux environment.

So:

wsl cat demo.txt
Enter fullscreen mode Exit fullscreen mode

runs the Linux command:

cat demo.txt
Enter fullscreen mode Exit fullscreen mode

without requiring you to manually enter the Linux shell first.

🛠️ Step 17 — Kali Linux Tweaks

If you are using Kali Linux, the notes mention:

kali-tweaks
Enter fullscreen mode Exit fullscreen mode

What is it used for?

kali-tweaks provides a way to configure and customize aspects of a Kali Linux installation.

You can explore the available options from the tool itself.

Run:

kali-tweaks
Enter fullscreen mode Exit fullscreen mode

and follow the interactive menus.

💡 This section is specific to Kali Linux. The command may not be available in other Linux distributions.

🔥 WSL's Windows ↔ Linux Integration

One of the biggest advantages of WSL is that Windows and Linux can work together.

Here is the basic relationship:

                 🪟 Windows
                    ↕
                   WSL
                    ↕
                 🐧 Linux
Enter fullscreen mode Exit fullscreen mode

You can:

🐧 Linux → Windows

Run Windows commands:

ping.exe
Enter fullscreen mode Exit fullscreen mode

Run Windows applications:

notepad.exe document.txt
Enter fullscreen mode Exit fullscreen mode

Open Windows Explorer:

explorer.exe .
Enter fullscreen mode Exit fullscreen mode

Launch VS Code:

code demo.py
Enter fullscreen mode Exit fullscreen mode

🪟 Windows → Linux

Run Linux commands from Windows:

wsl cat demo.txt
Enter fullscreen mode Exit fullscreen mode

This two-way integration is what makes WSL particularly convenient for development workflows.

🧠 Command Cheat Sheet

⚙️ Installation & Updates

Command Purpose
wsl --status Show WSL status/configuration information
wsl --update Update WSL
wsl --install --online Show distributions available for installation
wsl --install -d <distro> Install a specific distribution

📦 Distribution Management

Command Purpose
wsl --list List installed distributions
wsl --list --running List running distributions
wsl --list --verbose Show detailed distribution information
wsl --set-default <distro> Set the default distribution
wsl --unregister <distro> Remove/unregister a distribution

🚀 Starting & Stopping

Command Purpose
wsl Launch the default distribution
wsl -d <distro> Launch a specific distribution
exit Exit the current Linux shell
wsl --shutdown Shut down all WSL instances
wsl --terminate <distro> Terminate one distribution

🪟 Windows ↔ Linux Integration

Command Purpose
cd /mnt/c Access the Windows C: drive
explorer.exe . Open the current directory in Windows Explorer
notepad.exe document.txt Open a file in Windows Notepad
ping.exe Run the Windows ping executable from Linux
code demo.py Open a file in VS Code
wsl cat demo.txt Run a Linux command from Windows

🧪 Example: A Simple WSL Development Workflow

Here is a practical example combining several commands from this guide.

1️⃣ Check WSL

From PowerShell:

wsl --status
Enter fullscreen mode Exit fullscreen mode

2️⃣ Update WSL 

wsl --update
Enter fullscreen mode Exit fullscreen mode

3️⃣ Check installed distributions 

wsl --list --verbose
Enter fullscreen mode Exit fullscreen mode

4️⃣ Start Ubuntu 

wsl -d Ubuntu
Enter fullscreen mode Exit fullscreen mode

5️⃣ Navigate to a Windows project directory 

cd /mnt/c/Users/<your-username>/Desktop
Enter fullscreen mode Exit fullscreen mode

6️⃣ Create or access your project 

cd my-project
Enter fullscreen mode Exit fullscreen mode

7️⃣ Open the project in VS Code 

code .
Enter fullscreen mode Exit fullscreen mode

8️⃣ Open the same directory in Windows Explorer 

explorer.exe .
Enter fullscreen mode Exit fullscreen mode

This workflow demonstrates how Windows and Linux can work together without constantly switching environments.

🧩 Useful Mental Model

If you are new to WSL, remember these three rules:

Rule 1 — Windows drives live under /mnt 

C:\  →  /mnt/c
D:\  →  /mnt/d
Enter fullscreen mode Exit fullscreen mode

Rule 2 — Windows .exe programs can be launched from Linux 

notepad.exe
explorer.exe .
Enter fullscreen mode Exit fullscreen mode

Rule 3 — Linux commands can be launched from Windows using wsl 

wsl <linux-command>
Enter fullscreen mode Exit fullscreen mode

For example:

wsl cat demo.txt
Enter fullscreen mode Exit fullscreen mode

Once these three concepts become familiar, WSL becomes much easier to understand.

⚠️ Important Notes

  • 🔐 Some WSL installation operations may require an Administrator PowerShell.
  • 🔄 Restart Windows after enabling the required Windows features.
  • 🗑️ Be careful with wsl --unregister because it removes the selected distribution and its data.
  • 🐧 kali-tweaks is intended for Kali Linux.
  • 💻 For VS Code + WSL development, install the WSL extension in VS Code.
  • 📁 Windows drives are commonly accessed through /mnt/<drive-letter> from Linux.
  • 🛑 wsl --shutdown affects all running WSL distributions, while wsl --terminate <distro> targets one distribution.

📖 Official Documentation

For the latest and most authoritative information, always refer to Microsoft's official WSL documentation.

🖥️ WSL GUI Applications

Microsoft's WSL GUI applications guide:

https://learn.microsoft.com/en-us/windows/wsl/tutorials/gui-apps

📚 WSL Basic Commands

Microsoft's WSL basic commands documentation:

https://learn.microsoft.com/en-us/windows/wsl/basic-commands

🔎 WSL is actively maintained, so command behavior and supported features can change over time. The official Microsoft documentation should be treated as the final reference for current behavior.

🎉 Conclusion

WSL provides a powerful bridge between Windows and Linux.

With just a few commands, you can:

  • 🐧 Install and manage Linux distributions.
  • 🔄 Update and troubleshoot WSL.
  • 📦 Run multiple distributions.
  • 🪟 Access Windows files from Linux.
  • 💻 Run Windows applications from Linux.
  • 🐧 Run Linux commands from Windows.
  • 📝 Use VS Code with a Linux development environment.
  • 📂 Open Linux directories directly in Windows Explorer.

The most important commands to remember are:

wsl --status
wsl --update
wsl --list --verbose
wsl --install -d <distribution-name>
wsl --set-default <distribution-name>
wsl
wsl -d <distribution-name>
wsl --shutdown
wsl --terminate <distribution-name>
Enter fullscreen mode Exit fullscreen mode

And from inside Linux:

cd /mnt/c
explorer.exe .
notepad.exe document.txt
code demo.py
Enter fullscreen mode Exit fullscreen mode

Happy Linux-ing on Windows! 🐧💻🚀

Top comments (0)