Troubleshooting Windows Subsystem for Linux

  • Article
  • 19 minutes to read

We accept covered some mutual troubleshooting scenarios associated with WSL below, but delight consider searching the bug filed in the WSL product repo on GitHub as well.

File an issue, bug written report, characteristic asking

The WSL product repo issues enables you lot to:

  • Search existing problems to see if there are any associated with a problem that you are having. Note that in the search bar, you tin remove "is:open" to include issues that have already been resolved in your search. Please consider commenting or giving a thumbs upwards to any open issues that you lot would similar to express your involvement in moving forward as a priority.
  • File a new upshot. If y'all take found a problem with WSL and there does not appear to be an existing effect, you can select the green New issue push so cull WSL - Bug Study. You will demand to include a title for the issue, your Windows build number (run cmd.exe /c ver to meet your electric current build #), whether you're running WSL 1 or 2, your current Linux Kernel version # (run wsl.exe --status or cat /proc/version), the version # of your distribution (run lsb_release -r), any other software versions involved, the repro steps, expected behavior, actual beliefs, and diagnostic logs if available and advisable. For more info, see contributing to WSL.
  • File a characteristic request by selecting the green New issue button and then select Characteristic request. Y'all will need to address a few questions describing your asking.

You tin can also:

  • File a documentation issue using the WSL docs repo. To contribute to the WSL docs, see the Microsoft Docs correspondent guide.
  • File a Windows Terminal issue using the the Windows Last product repo if your problem is related more to the Windows Final, Windows Console, or the control-line UI.

Installation issues

  • Installation failed with fault 0x80070003

    • The Windows Subsystem for Linux only runs on your system drive (usually this is your C: drive). Make certain that distributions are stored on your arrangement drive:
    • Open Settings -> System --> Storage -> More Storage Settings: Change where new content is saved Picture of system settings to install apps on C: drive

  • WslRegisterDistribution failed with error 0x8007019e

    • The Windows Subsystem for Linux optional component is not enabled:
    • Open Control Panel -> Programs and Features -> Turn Windows Feature on or off -> Check Windows Subsystem for Linux or using the PowerShell cmdlet mentioned at the kickoff of this article.

  • Installation failed with error 0x80070003 or error 0x80370102

    • Please make sure that virtualization is enabled inside of your estimator'south BIOS. The instructions on how to do this will vary from figurer to figurer, and volition almost likely be under CPU related options.
    • WSL2 requires that your CPU supports the Second Level Address Translation (SLAT) feature, which was introduced in Intel Nehalem processors (Intel Core 1st Generation) and AMD Opteron. Older CPUs (such as the Intel Core 2 Duo) volition non be able to run WSL2, even if the Virtual Machine Platform is successfully installed.

  • Error when trying to upgrade: Invalid control line option: wsl --set-version Ubuntu ii

    • Ensure that you accept the Windows Subsystem for Linux enabled, and that yous're using Windows Build version 18362 or higher. To enable WSL run this command in a PowerShell prompt with admin privileges: Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux.

  • The requested operation could not be completed due to a virtual disk arrangement limitation. Virtual hard deejay files must exist uncompressed and unencrypted and must non be sparse.

    • Deselect "Compress contents" (also equally "Encrypt contents" if that's checked) by opening the profile folder for your Linux distribution. It should be located in a folder on your Windows file system, something like: %USERPROFILE%\AppData\Local\Packages\CanonicalGroupLimited...
    • In this Linux distro profile, there should be a LocalState folder. Right-click this binder to display a menu of options. Select Properties > Advanced and so ensure that the "Compress contents to save disk space" and "Encrypt contents to secure information" checkboxes are unselected (not checked). If you are asked whether to apply this to just to the current folder or to all subfolders and files, select "merely this folder" because you lot are merely clearing the compress flag. After this, the wsl --set-version control should work.

Screenshot of WSL distro property settings

Notation

In my example, the LocalState folder for my Ubuntu xviii.04 distribution was located at C:\Users<my-user-name>\AppData\Local\Packages\CanonicalGroupLimited.Ubuntu18.04onWindows_79rhkp1fndgsc

Check WSL Docs GitHub thread #4103 where this event is being tracked for updated data.

  • The term 'wsl' is not recognized every bit the name of a cmdlet, function, script file, or operable program.

    • Ensure that the Windows Subsystem for Linux Optional Component is installed. Additionally, if you are using an ARM64 device and running this command from PowerShell, you will receive this error. Instead run wsl.exe from PowerShell Cadre, or Control Prompt.

  • Error: Windows Subsystem for Linux has no installed distributions.

    • If you receive this error later you lot take already installed WSL distributions:
    1. Run the distribution at least in one case before invoking information technology from the command line.
    2. Check whether you may be running split up user accounts. Running your primary user business relationship with elevated permissions (in admin mode) should not upshot in this error, but y'all should ensure that you aren't accidentally running the built-in Administrator account that comes with Windows. This is a separate user account and volition not bear witness any installed WSL distributions by design. For more info, see Enable and Disable the Built-in Administrator Business relationship.
    3. The WSL executable is only installed to the native system directory. When you're running a 32-flake process on 64-fleck Windows (or on ARM64, any non-native combination), the hosted non-native process actually sees a different System32 folder. (The ane a 32-flake process sees on x64 Windows is stored on disk at \Windows\SysWOW64.) You can access the "native" system32 from a hosted process by looking in the virtual folder: \Windows\sysnative. Information technology won't actually be present on disk, mind you lot, but the filesystem path resolver will notice it.

  • Fault: This update merely applies to machines with the Windows Subsystem for Linux.

    • To install the Linux kernel update MSI packet, WSL is required and should be enabled first. If it fails, it y'all volition meet the message: This update only applies to machines with the Windows Subsystem for Linux.
    • There are three possible reason y'all run into this message:

    1. Y'all are even so in one-time version of Windows which doesn't support WSL ii. Run across step #2 for version requirements and links to update.

    2. WSL is not enabled. Yous will demand to return to step #i and ensure that the optional WSL feature is enabled on your automobile.

    3. Later you enabled WSL, a reboot is required for it to have consequence, reboot your car and try again.

  • Error: WSL 2 requires an update to its kernel component. For information delight visit https://aka.ms/wsl2kernel .

    • If the Linux kernel package is missing in the %SystemRoot%\system32\lxss\tools folder, you will encounter this fault. Resolve it by installing the Linux kernel update MSI package in step #4 of these installation instructions. You may need to uninstall the MSI from 'Add or Remove Programs', and install it again.

Common problems

I'm on Windows x version 1903 and I still do not see options for WSL 2

This is likely because your machine has not nevertheless taken the backport for WSL two. The simplest style to resolve this is by going to Windows Settings and clicking 'Bank check for Updates' to install the latest updates on your system. See the full instructions on taking the backport.

If you lot hitting 'Cheque for Updates' and still do non receive the update you lot can install KB KB4566116 manually.

Error: 0x1bc when wsl --prepare-default-version 2

This may happen when 'Display Language' or 'Organisation Locale' setting is not English.

              wsl --gear up-default-version 2 Mistake: 0x1bc For data on primal differences with WSL 2 delight visit https://aka.ms/wsl2

The actual error for 0x1bc is:

              WSL 2 requires an update to its kernel component. For information please visit https://aka.ms/wsl2kernel

For more data, please refer to issue 5749

Cannot access WSL files from Windows

A 9p protocol file server provides the service on the Linux side to allow Windows to access the Linux file system. If y'all cannot admission WSL using \\wsl$ on Windows, it could be because 9P did not kickoff correctly.

To check this, you can check the start up logs using: dmesg |grep 9p, and this will evidence you whatever errors. A successful output looks like the following:

              [    0.363323] 9p: Installing v9fs 9p2000 file system support [    0.363336] FS-Cache: Netfs '9p' registered for caching [    0.398989] 9pnet: Installing 9P2000 back up

Please see this Github thread for farther discussion on this consequence.

Can't start WSL two distribution and but see 'WSL 2' in output

If your brandish language is not English, then it is possible you are seeing a truncated version of an error text.

              C:\Users\me>wsl WSL ii

To resolve this issue, please visit https://aka.ms/wsl2kernel and install the kernel manually by following the directions on that physician page.

command not plant when executing windows .exe in linux

Users can run Windows executables like notepad.exe directly from Linux. Sometimes, you may hit "command not constitute" similar beneath:

              $ notepad.exe -bash: notepad.exe: command not constitute

If in that location are no win32 paths in your $PATH, interop isn't going to discover the .exe. You can verify it by running echo $PATH in Linux. It'southward expected that you volition meet a win32 path (for example, /mnt/c/Windows) in the output. If yous can't see whatsoever Windows paths then most likely your PATH is beingness overwritten past your Linux shell.

Here is a an instance that /etc/profile on Debian contributed to the problem:

              if [ "`id -u`" -eq 0 ]; and so   PATH="/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" else   PATH="/usr/local/bin:/usr/bin:/bin:/usr/local/games:/usr/games" fi

The correct way on Debian is to remove above lines. Yous may also append $PATH during the assignment like below, but this atomic number 82 to some other issues with WSL and VSCode..

              if [ "`id -u`" -eq 0 ]; then   PATH="/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:$PATH" else   PATH="/usr/local/bin:/usr/bin:/bin:/usr/local/games:/usr/games:$PATH" fi

For more than data, meet result 5296 and issue 5779.

"Fault: 0x80370102 The virtual automobile could not be started because a required characteristic is not installed."

Please enable the Virtual Machine Platform Windows feature and ensure virtualization is enabled in the BIOS.

  1. Check the Hyper-V organisation requirements

  2. If your machine is a VM, please enable nested virtualization manually. Launch powershell with admin, and run:

                      Set-VMProcessor -VMName <VMName> -ExposeVirtualizationExtensions $true

  3. Please follow guidelines from your PC'south manufacturer on how to enable virtualization. In general, this can involve using the system BIOS to ensure that these features are enabled on your CPU. Instructions for this procedure tin can vary from machine to machine, please see this article from Bleeping Calculator for an example.

  4. Restart your motorcar after enabling the Virtual Auto Platform optional component.

  5. Make sure that the hypervisor launch is enabled in your boot configuration. Yous can validate this by running (elevated powershell):

                                          bcdedit /enum | findstr -i hypervisorlaunchtype

    If you lot see hypervisorlaunchtype Off, so the hypervisor is disabled. To enable it run in an elevated powershell:

                                          bcdedit /set {current} hypervisorlaunchtype Auto

  6. Additionally, if you lot have 3rd political party hypervisors installed (Such as VMware or VirtualBox) and so please ensure you have these on the latest versions which tin support HyperV (VMware 15.5.v+ and VirtualBox half dozen+) or are turned off.

Learn more about how to Configure Nested Virtualization when running Hyper-V in a Virtual Automobile.

Bash loses network connectivity once continued to a VPN

If after connecting to a VPN on Windows, fustigate loses network connectivity, endeavour this workaround from within bash. This workaround volition allow yous to manually override the DNS resolution through /etc/resolv.conf.

  1. Take a note of the DNS server of the VPN from doing ipconfig.exe /all
  2. Brand a re-create of the existing resolv.conf sudo cp /etc/resolv.conf /etc/resolv.conf.new
  3. Unlink the current resolv.conf sudo unlink /etc/resolv.conf
  4. sudo mv /etc/resolv.conf.new /etc/resolv.conf
  5. Edit /etc/wsl.conf and add this content to the file. (More info on this fix can be constitute here)
              [network] generateResolvConf
  1. Open /etc/resolv.conf and
    a. Delete the starting time line from the file which has a comment describing automatic generation
    b. Add together the DNS entry from (one) above equally the very starting time entry in the list of DNS servers.
    c. Shut the file.

One time you accept disconnected the VPN, you volition take to revert the changes to /etc/resolv.conf. To practise this, do:

  1. cd /etc
  2. sudo mv resolv.conf resolv.conf.new
  3. sudo ln -s ../run/resolvconf/resolv.conf resolv.conf

Starting WSL or installing a distribution returns an error lawmaking

Follow these instructions to collect detailed logs and file an issue on our GitHub.

Updating WSL

There are two components of Windows Subsystem for Linux that can crave updating.

  1. To update the Windows Subsystem for Linux itself, utilize the command wsl --update in PowerShell or CMD.

  2. To update the specific Linux distribution user binaries, apply the control: apt-become update | apt-become upgrade in the Linux distribution that you are seeking to update.

Apt-get upgrade errors

Some packages use features that we haven't implemented yet. udev, for example, isn't supported nevertheless and causes several apt-go upgrade errors.

To fix issues related to udev, follow the following steps:

  1. Write the following to /usr/sbin/policy-rc.d and salvage your changes.

                      #!/bin/sh exit 101

  2. Add execute permissions to /usr/sbin/policy-rc.d:

                      chmod +ten /usr/sbin/policy-rc.d

  3. Run the following commands:

                      dpkg-divert --local --rename --add /sbin/initctl ln -s /bin/true /sbin/initctl

"Error: 0x80040306" on installation

This has to exercise with the fact that we practice not back up legacy console. To plough off legacy console:

  1. Open cmd.exe
  2. Correct click title bar -> Properties -> Uncheck Utilise legacy console
  3. Click OK

"Error: 0x80040154" after Windows update

The Windows Subsystem for Linux feature may be disabled during a Windows update. If this happens the Windows characteristic must be re-enabled. Instructions for enabling the Windows Subsystem for Linux can exist found in the Manual Installation Guide.

Changing the display linguistic communication

WSL install will try to automatically modify the Ubuntu locale to lucifer the locale of your Windows install. If you practise not desire this behavior you tin run this command to change the Ubuntu locale after install completes. Yous will have to relaunch bash.exe for this change to take effect.

The below instance changes to locale to en-US:

              sudo update-locale LANG=en_US.UTF8

Installation issues after Windows system restore

  1. Delete the %windir%\System32\Tasks\Microsoft\Windows\Windows Subsystem for Linux binder.
    Annotation: Do not do this if your optional feature is fully installed and working.
  2. Enable the WSL optional feature (if not already)
  3. Reboot
  4. lxrun /uninstall /full
  5. Install bash

No internet admission in WSL

Some users have reported issues with specific firewall applications blocking net admission in WSL. The firewalls reported are:

  1. Kaspersky
  2. AVG
  3. Avast
  4. Symantec Endpoint Protection

In some cases turning off the firewall allows for access. In some cases only having the firewall installed looks to block admission.

If y'all are using Microsoft Defender Firewall, unchecking "Blocks all incoming connections, including those in the listing of allowed apps." allows for access.

Permission Denied error when using ping

For Windows Anniversary Update, version 1607, administrator privileges in Windows are required to run ping in WSL. To run ping, run Bash on Ubuntu on Windows equally an administrator, or run bash.exe from a CMD/PowerShell prompt with administrator privileges.

For afterwards versions of Windows, Build 14926+, administrator privileges are no longer required.

Bash is hung

If while working with bash, y'all find that fustigate is hung (or deadlocked) and not responding to inputs, help us diagnose the issue by collecting and reporting a memory dump. Notation that these steps volition crash your system. Practise not practice this if you are non comfy with that or salvage your piece of work prior to doing this.

To collect a retentivity dump

  1. Change the retention dump type to "complete retention dump". While irresolute the dump type, have a note of your current blazon.

  2. Utilise the steps to configure crash using keyboard control.

  3. Repro the hang or deadlock.

  4. Crash the system using the key sequence from (two).

  5. The organisation will crash and collect the memory dump.

  6. Once the system reboots, report the memory.dmp to secure@microsoft.com. The default location of the dump file is %SystemRoot%\memory.dmp or C:\Windows\memory.dmp if C: is the system drive. In the e-mail, annotation that the dump is for the WSL or Bash on Windows team.

  7. Restore the retention dump blazon to the original setting.

Check your build number

To discover your PC'south architecture and Windows build number, open up
Settings > System > Most

Look for the OS Build and System Type fields.
Screenshot of Build and System Type fields

To detect your Windows Server build number, run the following in PowerShell:

              systeminfo | Select-String "^Os Name","^OS Version"

Confirm WSL is enabled

You can confirm that the Windows Subsystem for Linux is enabled by running the following in an elevated PowerShell window:

              Get-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux

OpenSSH-Server connectedness issues

Trying to connect your SSH server is failed with the following mistake: "Connectedness airtight by 127.0.0.i port 22".

  1. Make certain your OpenSSH Server is running:

                      sudo service ssh status

    and you've followed this tutorial: https://ubuntu.com/server/docs/service-openssh

  2. Finish the sshd service and start sshd in debug mode:

                      sudo service ssh terminate sudo /usr/sbin/sshd -d

  3. Check the startup logs and make sure HostKeys are available and yous don't see log messages such as:

                      debug1: sshd version OpenSSH_7.2, OpenSSL 1.0.2g  1 Mar 2016 debug1: key_load_private: incorrect passphrase supplied to decrypt individual key debug1: key_load_public: No such file or directory Could not load host cardinal: /etc/ssh/ssh_host_rsa_key debug1: key_load_private: No such file or directory debug1: key_load_public: No such file or directory Could not load host key: /etc/ssh/ssh_host_dsa_key debug1: key_load_private: No such file or directory debug1: key_load_public: No such file or directory Could not load host key: /etc/ssh/ssh_host_ecdsa_key debug1: key_load_private: No such file or directory debug1: key_load_public: No such file or directory Could not load host key: /etc/ssh/ssh_host_ed25519_key

If you lot practise see such letters and the keys are missing under /etc/ssh/, you will have to regenerate the keys or just purge&install openssh-server:

              sudo apt-get purge openssh-server sudo apt-get install openssh-server

"The referenced associates could not be constitute." when enabling the WSL optional characteristic

This fault is related to being in a bad install state. Please complete the following steps to attempt and fix this issue:

  • If you are running the enable WSL characteristic command from PowerShell, endeavour using the GUI instead by opening the start carte du jour, searching for 'Turn Windows features on or off' and then in the list select 'Windows Subsystem for Linux' which will install the optional component.

  • Update your version of Windows by going to Settings, Updates, and clicking 'Check for Updates'

  • If both of those fail and you need to access WSL delight consider upgrading in place by reinstalling Windows 10 using installation media and selecting 'Keep Everything' to ensure your apps and files are preserved. You can notice instructions on how to practice so at the Reinstall Windows ten page.

If yous're seeing this mistake:

              @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @         WARNING: UNPROTECTED PRIVATE KEY FILE!          @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ Permissions 0777 for '/home/artur/.ssh/private-central.pem' are too open up.

To fix this, append the following to the the /etc/wsl.conf file:

              [automount] enabled = truthful options = metadata,uid=1000,gid=g,umask=0022

Delight note that calculation this control volition include metadata and modify the file permissions on the Windows files seen from WSL. Please come across the File Organisation Permissions for more data.

Running Windows commands fails inside a distribution

Some distributions bachelor in Microsoft Store are yet non fully compatible to run Windows commands out of the box. If yous get an error -bash: powershell.exe: command not institute running powershell.exe /c start . or any other Windows command, y'all can resolve it following these steps:

  1. In your WSL distribution run repeat $PATH.
    If it does not include: /mnt/c/Windows/system32 something is redefining the standard PATH variable.
  2. Bank check contour settings with cat /etc/profile.
    If it contains assignment of the PATH variable, edit the file to comment out PATH assignment block with a # graphic symbol.
  3. Bank check if wsl.conf is present cat /etc/wsl.conf and make certain it does non incorporate appendWindowsPath=false, otherwise comment it out.
  4. Restart distribution by typing wsl -t followed past distribution name or run wsl --shutdown either in cmd or PowerShell.

Unable to boot later on installing WSL 2

We are aware of an upshot affecting users where they are unable to boot after installing WSL ii. While we fully diagnose those outcome, users accept reported that changing the buffer size or installing the right drivers can help address this. Please view this Github issue to see the latest updates on this effect.

WSL two errors when ICS is disabled

Internet Connection Sharing (ICS) is a required component of WSL 2. The ICS service is used past the Host Network Service (HNS) to create the underlying virtual network which WSL two relies on for NAT, DNS, DHCP, and host connectedness sharing.

Disabling the ICS service (SharedAccess) or disabling ICS through grouping policy will prevent the WSL HNS network from existence created. This will issue in failures when creating a new WSL version two image, and the post-obit error when trying to convert a version one image to version 2.

              There are no more endpoints available from the endpoint mapper.

Systems that require WSL 2 should leave the ICS service (SharedAccess) in it's default start state, Transmission (Trigger Kickoff), and any policy that disables ICS should be overwritten or removed. While disabling the ICS service volition break WSL 2, and nosotros do not recommend disabling ICS, portions of ICS can be disabled using these instructionsng-application-guard-)

Using older versions of Windows and WSL

There are several differences to notation if you're running an older version of Windows and WSL, similar the Windows 10 Creators Update (Oct 2017, Build 16299) or Ceremony Update (Aug 2016, Build 14393). We recommend that you lot update to the latest Windows version, but if that's not possible, nosotros have outlined some of the differences below.

Interoperability control differences:

  • fustigate.exe has been replaced with wsl.exe. Linux commands can be run from the Windows Command Prompt or from PowerShell, but for early Windows versions, you human need to use the bash command. For example: C:\temp> bash -c "ls -la". The WSL commands passed into bash -c are forwarded to the WSL process without modification. File paths must exist specified in the WSL format and intendance must be taken to escape relevant characters. For example: C:\temp> bash -c "ls -la /proc/cpuinfo" or C:\temp> fustigate -c "ls -la \"/mnt/c/Program Files\"".
  • To see what commands are available for a particular distribution, run [distro.exe] /?. For example, with Ubuntu: C:\> ubuntu.exe /?.
  • Windows path is included in the WSL $PATH.
  • When calling a Windows tool from a WSL distribution in an earlier version of Windows 10, you will need to specify the directory path. For instance, to phone call the Windows Notepad app from your WSL control line, enter: /mnt/c/Windows/System32/notepad.exe
  • To modify the default user to root use this control in PowerShell: C:\> lxrun /setdefaultuser root and and so run Bash.exe to log in: C:\> bash.exe. Reset your password using the distributions password control: $ passwd username so close the Linux command line: $ exit. From Windows command prompt or Powershell, reset your default user back to your normal Linux user business relationship: C:\> lxrun.exe /setdefaultuser username.

Uninstall legacy version of WSL

If you originally installed WSL on a version of Windows x prior to Creators update (Oct 2017, Build 16299), we recommend that you migrate whatever necessary files, information, etc. from the older Linux distribution you lot installed, to a newer distribution installed via the Microsoft Shop. To remove the legacy distribution from your machine, run the following from a Command Line or PowerShell case: wsl --unregister Legacy. You likewise accept the option to manually remove the older legacy distribution by deleting the %localappdata%\lxss\ folder (and all information technology's sub-contents) using Windows File Explorer or with PowerShell: rm -Recurse $env:localappdata/lxss/.