Troubleshooting Windows Subsystem for Linux

  • Article
  • 19 minutes to read

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

File an issue, issues report, feature asking

The WSL production repo issues enables you to:

  • Search existing bug to see if there are any associated with a problem that you are having. Note that in the search bar, you can remove "is:open" to include issues that have already been resolved in your search. Please consider commenting or giving a thumbs upward to any open issues that you would like to express your interest in moving forward every bit a priority.
  • File a new issue. If you have institute a trouble with WSL and in that location does non appear to exist an existing upshot, you can select the green New outcome push then choose WSL - Problems Written report. You will demand to include a championship for the issue, your Windows build number (run cmd.exe /c ver to see your current build #), whether yous're running WSL 1 or ii, 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 bachelor and appropriate. For more info, encounter contributing to WSL.
  • File a feature request past selecting the light-green New event button then select Feature request. You will need to address a few questions describing your request.

You lot can besides:

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

Installation issues

  • Installation failed with mistake 0x80070003

    • The Windows Subsystem for Linux only runs on your organization drive (unremarkably this is your C: bulldoze). Make sure that distributions are stored on your system drive:
    • Open Settings -> System --> Storage -> More Storage Settings: Alter 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 up Control Panel -> Programs and Features -> Turn Windows Characteristic on or off -> Check Windows Subsystem for Linux or using the PowerShell cmdlet mentioned at the start of this article.

  • Installation failed with mistake 0x80070003 or error 0x80370102

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

  • Error when trying to upgrade: Invalid command line option: wsl --set-version Ubuntu 2

    • Ensure that y'all have the Windows Subsystem for Linux enabled, and that you'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 performance could not be completed due to a virtual disk system limitation. Virtual hard deejay files must be uncompressed and unencrypted and must not be thin.

    • Deselect "Compress contents" (also every bit "Encrypt contents" if that's checked) by opening the profile binder 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 folder to display a menu of options. Select Properties > Advanced and then 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 employ this to merely to the electric current folder or to all subfolders and files, select "but this folder" because y'all are merely clearing the compress flag. After this, the wsl --set-version command should work.

Screenshot of WSL distro property settings

Note

In my instance, the LocalState folder for my Ubuntu 18.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 issue is beingness tracked for updated information.

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

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

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

    • If yous receive this fault subsequently you have already installed WSL distributions:
    1. Run the distribution at to the lowest degree once before invoking it from the control line.
    2. Check whether you may be running separate user accounts. Running your primary user account with elevated permissions (in admin style) should not event in this fault, but you should ensure that you aren't accidentally running the congenital-in Administrator account that comes with Windows. This is a separate user business relationship and will not show any installed WSL distributions by design. For more than info, see Enable and Disable the Built-in Administrator Account.
    3. The WSL executable is merely installed to the native organisation directory. When you lot're running a 32-flake process on 64-bit Windows (or on ARM64, whatever non-native combination), the hosted non-native process actually sees a unlike System32 folder. (The 1 a 32-bit process sees on x64 Windows is stored on deejay at \Windows\SysWOW64.) Yous can access the "native" system32 from a hosted procedure by looking in the virtual binder: \Windows\sysnative. It won't actually be present on disk, heed yous, just the filesystem path resolver will discover it.

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

    • To install the Linux kernel update MSI package, WSL is required and should exist enabled first. If it fails, it yous volition encounter the message: This update only applies to machines with the Windows Subsystem for Linux.
    • There are 3 possible reason you see this message:

    1. You are still in old version of Windows which doesn't support WSL 2. See stride #2 for version requirements and links to update.

    2. WSL is non enabled. Yous will need to return to footstep #i and ensure that the optional WSL characteristic is enabled on your machine.

    3. After yous enabled WSL, a reboot is required for information technology to take event, reboot your machine and attempt once again.

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

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

Common issues

I'1000 on Windows x version 1903 and I all the same do not encounter options for WSL 2

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

If yous hit 'Check for Updates' and still practise not receive the update you lot can install KB KB4566116 manually.

Mistake: 0x1bc when wsl --set up-default-version 2

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

              wsl --set-default-version ii Fault: 0x1bc For information on key differences with WSL ii delight visit https://aka.ms/wsl2

The bodily fault for 0x1bc is:

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

For more than information, please refer to effect 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 you lot cannot access WSL using \\wsl$ on Windows, it could be because 9P did not start correctly.

To check this, you can bank check the start up logs using: dmesg |grep 9p, and this will bear witness yous any errors. A successful output looks like the post-obit:

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

Please see this Github thread for further discussion on this issue.

Tin't start WSL 2 distribution and merely run across 'WSL 2' in output

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

              C:\Users\me>wsl WSL ii

To resolve this outcome, please visit https://aka.ms/wsl2kernel and install the kernel manually by post-obit the directions on that dr. page.

control not establish when executing windows .exe in linux

Users can run Windows executables like notepad.exe directly from Linux. Sometimes, you may hitting "control not establish" like beneath:

              $ notepad.exe -bash: notepad.exe: control not establish

If there are no win32 paths in your $PATH, interop isn't going to find the .exe. You can verify information technology by running echo $PATH in Linux. It's expected that you will encounter a win32 path (for example, /mnt/c/Windows) in the output. If you tin't see any Windows paths and so most likely your PATH is beingness overwritten past your Linux trounce.

Hither is a an example that /etc/profile on Debian contributed to the problem:

              if [ "`id -u`" -eq 0 ]; then   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 style on Debian is to remove above lines. You may likewise suspend $PATH during the assignment like beneath, but this lead to some other problems 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 information, see issue 5296 and issue 5779.

"Error: 0x80370102 The virtual automobile could non exist started because a required characteristic is non installed."

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

  1. Cheque the Hyper-5 arrangement requirements

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

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

  3. Delight follow guidelines from your PC's manufacturer on how to enable virtualization. In full general, this can involve using the system BIOS to ensure that these features are enabled on your CPU. Instructions for this procedure tin vary from car to machine, delight see this commodity from Bleeping Computer for an case.

  4. Restart your automobile after enabling the Virtual Automobile Platform optional component.

  5. Brand sure that the hypervisor launch is enabled in your kicking configuration. Y'all tin can validate this by running (elevated powershell):

                                          bcdedit /enum | findstr -i hypervisorlaunchtype

    If y'all come across hypervisorlaunchtype Off, and then the hypervisor is disabled. To enable it run in an elevated powershell:

                                          bcdedit /gear up {current} hypervisorlaunchtype Car

  6. Additionally, if you take third party hypervisors installed (Such as VMware or VirtualBox) then please ensure you have these on the latest versions which tin can support HyperV (VMware 15.5.5+ and VirtualBox six+) or are turned off.

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

Bash loses network connectivity in one case continued to a VPN

If later connecting to a VPN on Windows, fustigate loses network connectivity, attempt this workaround from within bash. This workaround will allow y'all 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. Make a copy of the existing resolv.conf sudo cp /etc/resolv.conf /etc/resolv.conf.new
  3. Unlink the electric 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 set up can be institute here)
              [network] generateResolvConf
  1. Open /etc/resolv.conf and
    a. Delete the first line from the file which has a comment describing automatic generation
    b. Add the DNS entry from (one) higher up as the very beginning entry in the list of DNS servers.
    c. Shut the file.

Once you have asunder the VPN, yous will take to revert the changes to /etc/resolv.conf. To do this, exercise:

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

Starting WSL or installing a distribution returns an fault code

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

Updating WSL

There are two components of Windows Subsystem for Linux that can require 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, use the control: apt-go update | apt-get upgrade in the Linux distribution that y'all are seeking to update.

Apt-get upgrade errors

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

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

  1. Write the post-obit to /usr/sbin/policy-rc.d and save your changes.

                      #!/bin/sh exit 101

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

                      chmod +x /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 practise with the fact that we practice not support legacy console. To turn off legacy console:

  1. Open cmd.exe
  2. Right click championship bar -> Properties -> Uncheck Use legacy console
  3. Click OK

"Fault: 0x80040154" after Windows update

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

Irresolute the display language

WSL install will endeavor to automatically alter the Ubuntu locale to match the locale of your Windows install. If you practice not want this behavior you can run this command to change the Ubuntu locale after install completes. You will accept to relaunch bash.exe for this modify to accept 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.
    Note: Do non 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 access in WSL

Some users take reported bug with specific firewall applications blocking internet access 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 admission. In some cases simply having the firewall installed looks to block admission.

If you lot are using Microsoft Defender Firewall, unchecking "Blocks all incoming connections, including those in the list of allowed apps." allows for admission.

Permission Denied error when using ping

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

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

Fustigate is hung

If while working with fustigate, you find that fustigate is hung (or deadlocked) and not responding to inputs, assist usa diagnose the effect by collecting and reporting a memory dump. Note that these steps will crash your system. Do not exercise this if you are not comfy with that or salve your work prior to doing this.

To collect a memory dump

  1. Change the memory dump type to "complete memory dump". While changing the dump type, take a note of your current blazon.

  2. Use the steps to configure crash using keyboard command.

  3. Repro the hang or deadlock.

  4. Crash the arrangement using the cardinal sequence from (2).

  5. The system will crash and collect the retentivity 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\retentiveness.dmp if C: is the organisation drive. In the email, annotation that the dump is for the WSL or Bash on Windows team.

  7. Restore the memory dump type to the original setting.

Check your build number

To find your PC's architecture and Windows build number, open up
Settings > Arrangement > Virtually

Look for the Os Build and System Blazon fields.
Screenshot of Build and System Type fields

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

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

Confirm WSL is enabled

You tin ostend that the Windows Subsystem for Linux is enabled past running the post-obit in an elevated PowerShell window:

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

OpenSSH-Server connectedness problems

Trying to connect your SSH server is failed with the following error: "Connexion closed 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. End the sshd service and starting time sshd in debug fashion:

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

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

                      debug1: sshd version OpenSSH_7.2, OpenSSL 1.0.2g  one Mar 2016 debug1: key_load_private: incorrect passphrase supplied to decrypt individual fundamental debug1: key_load_public: No such file or directory Could not load host fundamental: /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 central: /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 do come across such messages and the keys are missing under /etc/ssh/, you volition take to regenerate the keys or just purge&install openssh-server:

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

"The referenced associates could not be found." when enabling the WSL optional feature

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

  • If you are running the enable WSL feature control from PowerShell, try using the GUI instead by opening the start menu, searching for 'Turn Windows features on or off' and then in the list select 'Windows Subsystem for Linux' which volition install the optional component.

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

  • If both of those fail and you need to access WSL please 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 detect instructions on how to do so at the Reinstall Windows 10 page.

If you're seeing this error:

              @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @         WARNING: UNPROTECTED Individual Primal FILE!          @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ Permissions 0777 for '/home/artur/.ssh/individual-fundamental.pem' are also open.

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

              [automount] enabled = true options = metadata,uid=1000,gid=thousand,umask=0022

Please notation that adding this command volition include metadata and modify the file permissions on the Windows files seen from WSL. Please see the File Organization Permissions for more information.

Running Windows commands fails inside a distribution

Some distributions available in Microsoft Shop are notwithstanding non fully compatible to run Windows commands out of the box. If yous become an error -fustigate: powershell.exe: command not found running powershell.exe /c outset . or whatever other Windows command, you can resolve it following these steps:

  1. In your WSL distribution run echo $PATH.
    If information technology does not include: /mnt/c/Windows/system32 something is redefining the standard PATH variable.
  2. Check profile settings with cat /etc/profile.
    If it contains consignment of the PATH variable, edit the file to comment out PATH assignment block with a # graphic symbol.
  3. Check if wsl.conf is nowadays cat /etc/wsl.conf and make sure information technology does not comprise appendWindowsPath=imitation, otherwise comment it out.
  4. Restart distribution past typing wsl -t followed by distribution proper noun or run wsl --shutdown either in cmd or PowerShell.

Unable to kick after installing WSL 2

Nosotros are aware of an issue affecting users where they are unable to boot after installing WSL 2. While nosotros fully diagnose those issue, users accept reported that irresolute the buffer size or installing the right drivers tin can help address this. Please view this Github issue to see the latest updates on this effect.

WSL 2 errors when ICS is disabled

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

Disabling the ICS service (SharedAccess) or disabling ICS through group policy will forbid the WSL HNS network from beingness created. This will result in failures when creating a new WSL version 2 paradigm, and the post-obit error when trying to convert a version i image to version two.

              At that place are no more endpoints available from the endpoint mapper.

Systems that crave WSL 2 should leave the ICS service (SharedAccess) in it's default start land, Manual (Trigger Outset), and any policy that disables ICS should be overwritten or removed. While disabling the ICS service will break WSL ii, and we practice not recommend disabling ICS, portions of ICS can be disabled using these instructionsng-application-guard-)

Using older versions of Windows and WSL

In that location are several differences to notation if yous're running an older version of Windows and WSL, like the Windows 10 Creators Update (October 2017, Build 16299) or Anniversary Update (Aug 2016, Build 14393). We recommend that you update to the latest Windows version, but if that's non possible, we have outlined some of the differences below.

Interoperability command differences:

  • bash.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, y'all human being demand to use the bash command. For example: C:\temp> bash -c "ls -la". The WSL commands passed into fustigate -c are forwarded to the WSL process without modification. File paths must exist specified in the WSL format and care must be taken to escape relevant characters. For instance: C:\temp> bash -c "ls -la /proc/cpuinfo" or C:\temp> fustigate -c "ls -la \"/mnt/c/Plan 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 before version of Windows x, you volition need to specify the directory path. For example, to call the Windows Notepad app from your WSL control line, enter: /mnt/c/Windows/System32/notepad.exe
  • To change the default user to root use this control in PowerShell: C:\> lxrun /setdefaultuser root and then run Bash.exe to log in: C:\> bash.exe. Reset your countersign using the distributions password command: $ passwd username and so close the Linux command line: $ exit. From Windows control prompt or Powershell, reset your default user dorsum 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 10 prior to Creators update (October 2017, Build 16299), we recommend that yous migrate any necessary files, data, etc. from the older Linux distribution you installed, to a newer distribution installed via the Microsoft Store. To remove the legacy distribution from your motorcar, run the following from a Command Line or PowerShell instance: wsl --unregister Legacy. You also take the option to manually remove the older legacy distribution past deleting the %localappdata%\lxss\ binder (and all information technology'south sub-contents) using Windows File Explorer or with PowerShell: rm -Recurse $env:localappdata/lxss/.