sodcalculator

10 Tech How-To

Enable Linux Bash Shell on Windows 10 (WSL)

Guide 10-44235 · Updated · Step by step

This guide walks you through enabling the Windows Subsystem for Linux (WSL) on Windows 10, which lets you run a real Linux bash shell directly on your Windows machine without a virtual machine. You’ll be able to install and use popular Linux distributions like Ubuntu, Debian, or openSUSE right from the Start menu. Before you start, make sure you’re running a 64-bit version of Windows 10 (or Windows Server 2019) and that you have administrator access to your PC.

What You’ll Need

  • A PC running 64-bit Windows 10 (version 1607 or later for the basic install, version 1903 or later for the easiest method).
  • Administrator privileges on that PC.
  • An internet connection to download the Linux distribution from the Microsoft Store.
  • Optional but recommended: a backup of important files before making system changes.

Step-by-Step

  1. Enable the Windows Subsystem for Linux feature. Open the Start menu, search for “Turn Windows features on or off,” and click the top result. In the list, scroll down, check the box next to “Windows Subsystem for Linux,” and click OK. Windows will install the necessary components and then ask you to restart your computer. Do so.
  2. Enable the Virtual Machine Platform (optional but recommended for WSL 2). After restarting, open the same “Turn Windows features on or off” dialog again, find “Virtual Machine Platform,” check it, and click OK. This is required for WSL 2, which offers better performance and full system call compatibility. Restart again if prompted.
  3. Set WSL 2 as your default version (optional). Open PowerShell as Administrator (right-click Start, select “Windows PowerShell (Admin)”). Run the command: wsl --set-default-version 2. If you see a message about needing a kernel update, download and install the latest WSL 2 Linux kernel from the Microsoft website, then run the command again.
  4. Install a Linux distribution. Open the Microsoft Store from the Start menu. Search for “Linux” or the name of a specific distribution like “Ubuntu” or “Debian.” Click on the one you want (Ubuntu is the most popular and well-documented), then click “Get” or “Install.” Wait for the download and installation to finish.
  5. Launch the distribution. Click the “Launch” button in the Store, or find the distribution in your Start menu (e.g., “Ubuntu”). The first launch will open a console window and ask you to create a username and password for the Linux environment. This is separate from your Windows credentials.
  6. Update your Linux packages. Once you’re at the bash prompt, run sudo apt update and then sudo apt upgrade (for Debian/Ubuntu-based systems) to ensure you have the latest software and security patches. Enter your Linux password when prompted.
  7. Verify the installation. Type lsb_release -a (for Ubuntu) or cat /etc/os-release to see the distribution version. You can also run bash --version to confirm the shell is working.

Common Mistakes

  • Skipping the restart. The WSL feature won’t work until you reboot. Always restart when Windows asks.
  • Not enabling Virtual Machine Platform. If you try to use WSL 2 without this feature, you’ll get an error. Enable it and restart.
  • Installing a 32-bit distribution. WSL only supports 64-bit distributions. If you try to install a 32-bit one, it will fail.
  • Forgetting the Linux password. You’ll need this password for sudo commands. If you forget it, you can reset it from Windows by running wsl -u root in PowerShell and then using passwd.
  • Using the wrong command for your distribution. Package manager commands differ: Ubuntu/Debian use apt, Fedora uses dnf, openSUSE uses zypper. Check the distribution’s documentation.

Tips

  • Access your Windows files from Linux. Your C: drive is mounted at /mnt/c/. For example, cd /mnt/c/Users/YourName/Documents will take you to your Windows Documents folder.
  • Access your Linux files from Windows. In File Explorer, type \\wsl$ in the address bar to see your Linux file system.
  • Run Linux commands from PowerShell or CMD. Use wsl [command] to execute a single Linux command without opening the full shell. For example, wsl ls -la.
  • Set your default distribution. If you install multiple distributions, use wsl --set-default <distro> in PowerShell to choose which one opens when you type wsl.
  • Use WSL 2 for better performance. WSL 2 offers faster file I/O and full system call compatibility. You can check your version with wsl --list --verbose.

Troubleshooting

  • Error: “Windows Subsystem for Linux has no installed distributions.” This means you haven’t installed a distribution yet. Go to the Microsoft Store and install one.
  • Error: “WSL 2 requires an update to its kernel component.” Download the latest WSL 2 kernel update from the Microsoft website, install it, and then run wsl --set-default-version 2 again.
  • Error: “The operation timed out.” This often happens during first launch when the distribution is initializing. Wait a few minutes, then close and reopen the terminal. If it persists, restart your PC.
  • Bash opens but is stuck at a black screen. Try restarting the WSL service: in PowerShell (Admin), run wsl --shutdown, then launch your distribution again.
  • Forgot your Linux password. In PowerShell (Admin), run wsl -u root to enter the root shell, then use passwd <username> to reset the password.
  • Distribution won’t install from the Store. Make sure your Windows is up to date. You can also try downloading the distribution’s appx package from the Microsoft website, but the Store method is the most reliable.

Frequently Asked Questions

Can I run GUI Linux applications with WSL?

Yes, with WSL 2 and Windows 10 version 19044+ (or Windows 11), you can run GUI apps using WSLg or by installing an X server like Xming. Many popular apps like Firefox or GIMP work well.

Will WSL slow down my PC?

No, WSL is lightweight. It runs in the background only when you use it, and it uses the same memory management as Windows. You can set a memory limit in .wslconfig if needed.

Can I access my Windows files from Linux?

Yes, your Windows drives are mounted under /mnt/. For example, your C: drive is at /mnt/c/. You can read and write files there, but for best performance, keep Linux files inside the Linux file system.

How do I uninstall a Linux distribution?

Go to Settings > Apps > Apps & features, find the distribution (e.g., Ubuntu), and click Uninstall. This removes the distribution and its data. You can also disable the WSL feature entirely from “Turn Windows features on or off.”

Is WSL free?

Yes, WSL itself is a free Windows feature, and the distributions available in the Microsoft Store are also free. You only need a valid Windows 10 license.

Can I run Docker inside WSL 2?

Yes, Docker Desktop for Windows can use WSL 2 as its backend. You can also install the Docker engine directly inside your WSL distribution, but Docker Desktop is the easiest way to get started.

Related

General steps for current mainstream versions; menus can differ by device and version. See the disclaimer or report an error.

More in this bed

The whole Tech How-To bed →