Troubleshooting Windows Subsystem for Linux

  • Article
  • 19 minutes to read

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

File an issue, bug report, characteristic request

The WSL product repo issues enables you to:

  • Search existing issues to see if there are whatever associated with a problem that you are having. Annotation that in the search bar, you tin remove "is:open" to include issues that have already been resolved in your search. Delight consider commenting or giving a thumbs up to whatever open up issues that you lot would like to limited your involvement in moving frontward as a priority.
  • File a new issue. If you have found a problem with WSL and in that location does not appear to be an existing issue, you can select the light-green New consequence push and then choose WSL - Bug Report. Yous will demand to include a title for the consequence, your Windows build number (run cmd.exe /c ver to come across your current build #), whether you're running WSL 1 or 2, your current Linux Kernel version # (run wsl.exe --condition or cat /proc/version), the version # of your distribution (run lsb_release -r), any other software versions involved, the repro steps, expected behavior, actual behavior, and diagnostic logs if available and appropriate. For more info, see contributing to WSL.
  • File a characteristic asking past selecting the green New outcome button and then select Feature request. You volition need to accost a few questions describing your request.

You tin also:

  • 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 result using the the Windows Terminal product repo if your problem is related more to the Windows Terminal, Windows Panel, or the command-line UI.

Installation bug

  • Installation failed with error 0x80070003

  • WslRegisterDistribution failed with error 0x8007019e

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

  • Installation failed with error 0x80070003 or mistake 0x80370102

    • Delight make sure that virtualization is enabled inside of your computer's BIOS. The instructions on how to practise this will vary from reckoner to reckoner, and volition most probable exist 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 two Duo) will not exist able to run WSL2, fifty-fifty if the Virtual Car Platform is successfully installed.

  • Mistake when trying to upgrade: Invalid command line option: wsl --fix-version Ubuntu 2

    • Ensure that y'all have the Windows Subsystem for Linux enabled, and that yous're using Windows Build version 18362 or later. To enable WSL run this control 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 system limitation. Virtual hard disk drive files must exist uncompressed and unencrypted and must not be thin.

    • Deselect "Shrink contents" (besides every bit "Encrypt contents" if that's checked) by opening the contour folder for your Linux distribution. Information technology should be located in a folder on your Windows file system, something like: %USERPROFILE%\AppData\Local\Packages\CanonicalGroupLimited...
    • In this Linux distro contour, there should be a LocalState binder. 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 data" checkboxes are unselected (not checked). If you are asked whether to apply this to just to the current binder or to all subfolders and files, select "only this folder" considering you are but clearing the compress flag. After this, the wsl --fix-version command should work.

Screenshot of WSL distro property settings

Note

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

Bank check WSL Docs GitHub thread #4103 where this issue is being tracked for updated information.

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

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

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

    • If you receive this error subsequently you take already installed WSL distributions:
    1. Run the distribution at least once before invoking it from the command line.
    2. Check whether yous may exist running divide user accounts. Running your primary user account with elevated permissions (in admin mode) should not result in this error, but yous should ensure that you aren't accidentally running the built-in Ambassador account that comes with Windows. This is a split user account and will not testify any installed WSL distributions by design. For more than info, encounter Enable and Disable the Congenital-in Ambassador Account.
    3. The WSL executable is only installed to the native organization directory. When you're running a 32-bit process on 64-bit Windows (or on ARM64, any not-native combination), the hosted non-native process actually sees a different System32 folder. (The one a 32-bit 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 binder: \Windows\sysnative. Information technology won't actually exist present on deejay, mind y'all, but the filesystem path resolver will find information technology.

  • Error: This update just applies to machines with the Windows Subsystem for Linux.

    • To install the Linux kernel update MSI packet, WSL is required and should exist enabled kickoff. If it fails, it yous will see the bulletin: This update only applies to machines with the Windows Subsystem for Linux.
    • There are three possible reason you come across this message:

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

    2. WSL is not enabled. You will need to return to footstep #1 and ensure that the optional WSL feature is enabled on your machine.

    3. After yous enabled WSL, a reboot is required for it to take effect, reboot your machine and effort again.

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

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

Mutual problems

I'thousand on Windows 10 version 1903 and I still practice non see options for WSL two

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

If you striking 'Bank check for Updates' and nevertheless practise not receive the update you can install KB KB4566116 manually.

Mistake: 0x1bc when wsl --set-default-version two

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

              wsl --ready-default-version 2 Error: 0x1bc For information on key differences with WSL 2 please visit https://aka.ms/wsl2

The actual error for 0x1bc is:

              WSL two requires an update to its kernel component. For data delight visit https://aka.ms/wsl2kernel

For more information, please refer to upshot 5749

Cannot access WSL files from Windows

A 9p protocol file server provides the service on the Linux side to let Windows to access the Linux file organization. If you lot cannot access WSL using \\wsl$ on Windows, it could exist because 9P did not kickoff correctly.

To check this, you can bank check the offset up logs using: dmesg |grep 9p, and this will testify you whatever errors. A successful output looks similar the following:

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

Delight encounter this Github thread for further discussion on this effect.

Can't start WSL 2 distribution and only come across 'WSL 2' in output

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

              C:\Users\me>wsl WSL ii

To resolve this consequence, please visit https://aka.ms/wsl2kernel and install the kernel manually by following the directions on that medico folio.

command non constitute when executing windows .exe in linux

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

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

If at that place are no win32 paths in your $PATH, interop isn't going to find the .exe. You can verify information technology by running repeat $PATH in Linux. It's expected that you volition run across a win32 path (for instance, /mnt/c/Windows) in the output. If you can't see any Windows paths then most probable your PATH is being overwritten by your Linux shell.

Here is a an case that /etc/profile on Debian contributed to the trouble:

              if [ "`id -u`" -eq 0 ]; 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 right mode on Debian is to remove above lines. Y'all may also suspend $PATH during the assignment like below, but this lead to another problems with WSL and VSCode..

              if [ "`id -u`" -eq 0 ]; and 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 data, see issue 5296 and issue 5779.

"Error: 0x80370102 The virtual automobile could not be started considering 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 system requirements

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

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

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

  4. Restart your machine afterward enabling the Virtual Machine Platform optional component.

  5. Brand sure that the hypervisor launch is enabled in your kick configuration. You lot can validate this by running (elevated powershell):

                                          bcdedit /enum | findstr -i hypervisorlaunchtype

    If yous meet hypervisorlaunchtype Off, then the hypervisor is disabled. To enable it run in an elevated powershell:

                                          bcdedit /gear up {current} hypervisorlaunchtype Auto

  6. Additionally, if you have tertiary party hypervisors installed (Such as VMware or VirtualBox) so please ensure y'all have these on the latest versions which can support HyperV (VMware fifteen.5.5+ and VirtualBox 6+) or are turned off.

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

Fustigate loses network connectivity one time continued to a VPN

If later connecting to a VPN on Windows, bash loses network connectivity, try this workaround from within fustigate. This workaround will permit you 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 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 together this content to the file. (More than info on this set up can be plant in Advanced settings configuration)
              [network] generateResolvConf=imitation
  1. Open /etc/resolv.conf and
    a. Delete the offset line from the file which has a comment describing automatic generation
    b. Add the DNS entry from (i) above as the very first entry in the listing of DNS servers.
    c. Close the file.

One time you have disconnected the VPN, you will have to revert the changes to /etc/resolv.conf. To practice this, practice:

  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 mistake code

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

Updating WSL

In that location are two components of Windows Subsystem for Linux that tin 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, utilize the command: apt-go update | apt-get upgrade in the Linux distribution that you are seeking to update.

Apt-go upgrade errors

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

To prepare issues 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 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/truthful /sbin/initctl

"Error: 0x80040306" on installation

This has to practise with the fact that we do not support legacy panel. To plough off legacy console:

  1. Open up cmd.exe
  2. Correct click title bar -> Backdrop -> Uncheck Employ 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 feature must be re-enabled. Instructions for enabling the Windows Subsystem for Linux can be found in the Manual Installation Guide.

Changing the display linguistic communication

WSL install will attempt to automatically modify the Ubuntu locale to friction match the locale of your Windows install. If you do not desire this beliefs you can run this command to change the Ubuntu locale subsequently install completes. You will accept to relaunch fustigate.exe for this change to take event.

The below example changes to locale to en-U.s.:

              sudo update-locale LANG=en_US.UTF8

Installation issues later on Windows system restore

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

No net access in WSL

Some users take reported issues with specific firewall applications blocking cyberspace 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 cake access.

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

Permission Denied mistake when using ping

For Windows Anniversary Update, version 1607, ambassador privileges in Windows are required to run ping in WSL. To run ping, run Bash on Ubuntu on Windows as an ambassador, 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.

Bash is hung

If while working with bash, you lot find that bash is hung (or deadlocked) and non responding to inputs, help u.s.a. diagnose the effect past collecting and reporting a retention dump. Notation that these steps will crash your system. Practice non do this if you are non comfortable with that or save your piece of work prior to doing this.

To collect a retentivity dump

  1. Alter the memory dump type to "consummate memory dump". While changing the dump type, take a note of your current type.

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

  3. Repro the hang or deadlock.

  4. Crash the organization using the cardinal sequence from (two).

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

  6. One time the system reboots, report the memory.dmp to secure@microsoft.com. The default location of the dump file is %SystemRoot%\retentivity.dmp or C:\Windows\memory.dmp if C: is the system drive. In the electronic mail, note 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 observe your PC's compages and Windows build number, open
Settings > System > Near

Wait for the Os Build and System Type fields.
Screenshot of Build and System Type fields

To notice your Windows Server build number, run the post-obit in PowerShell:

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

Ostend WSL is enabled

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

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

OpenSSH-Server connection issues

Trying to connect your SSH server is failed with the following mistake: "Connection closed by 127.0.0.ane port 22".

  1. Make sure your OpenSSH Server is running:

                      sudo service ssh status

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

  2. Stop the sshd service and start sshd in debug manner:

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

  3. Check the startup logs and make certain HostKeys are available and you don't run into log messages such equally:

                      debug1: sshd version OpenSSH_7.2, OpenSSL 1.0.2g  i Mar 2016 debug1: key_load_private: incorrect passphrase supplied to decrypt private key 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 cardinal: /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 non load host primal: /etc/ssh/ssh_host_ed25519_key

If y'all do run across such messages and the keys are missing under /etc/ssh/, you volition have to regenerate the keys or just purge&install openssh-server:

              sudo apt-go purge openssh-server sudo apt-go install openssh-server

"The referenced assembly could non be found." when enabling the WSL optional characteristic

This error is related to being in a bad install state. Delight complete the post-obit steps to endeavour and fix this effect:

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

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

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

If yous're seeing this error:

              @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @         WARNING: UNPROTECTED PRIVATE KEY FILE!          @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ Permissions 0777 for '/dwelling house/artur/.ssh/individual-key.pem' are also open.

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

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

Delight notation that adding this command will include metadata and alter the file permissions on the Windows files seen from WSL. Please run across the File System Permissions for more information.

Running Windows commands fails within a distribution

Some distributions available in Microsoft Store are yet not fully compatible to run Windows commands out of the box. If you get an mistake -bash: powershell.exe: control not found running powershell.exe /c start . or any other Windows control, you tin resolve it following these steps:

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

Unable to boot after installing WSL 2

Nosotros are aware of an issue affecting users where they are unable to kick after installing WSL two. While we fully diagnose those upshot, users accept reported that changing the buffer size or installing the right drivers tin can help accost this. Delight view this Github effect to run into the latest updates on this issue.

WSL two errors when ICS is disabled

Cyberspace Connexion 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 two relies on for NAT, DNS, DHCP, and host connectedness sharing.

Disabling the ICS service (SharedAccess) or disabling ICS through group policy will prevent the WSL HNS network from being created. This will result in failures when creating a new WSL version 2 image, and the post-obit mistake when trying to convert a version 1 image to version ii.

              There are no more endpoints bachelor from the endpoint mapper.

Systems that require WSL ii should leave the ICS service (SharedAccess) in information technology'due south default commencement country, Manual (Trigger Start), and whatsoever policy that disables ICS should be overwritten or removed. While disabling the ICS service volition intermission WSL 2, and we practise not recommend disabling ICS, portions of ICS tin exist disabled using these instructionsng-awarding-baby-sit-)

Using older versions of Windows and WSL

There are several differences to annotation if you're running an older version of Windows and WSL, like the Windows 10 Creators Update (Oct 2017, Build 16299) or Ceremony Update (Aug 2016, Build 14393). We recommend that you update to the latest Windows version, but if that'southward not possible, we take outlined some of the differences beneath.

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, y'all homo need to utilize the bash command. For instance: C:\temp> bash -c "ls -la". The WSL commands passed into bash -c are forwarded to the WSL process without modification. File paths must be specified in the WSL format and care must be taken to escape relevant characters. For example: C:\temp> fustigate -c "ls -la /proc/cpuinfo" or C:\temp> bash -c "ls -la \"/mnt/c/Program Files\"".
  • To come across what commands are available for a detail 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 demand 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 alter the default user to root employ this command in PowerShell: C:\> lxrun /setdefaultuser root then 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: $ get out. From Windows control 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), nosotros recommend that you migrate any necessary files, information, etc. from the older Linux distribution you installed, to a newer distribution installed via the Microsoft Shop. To remove the legacy distribution from your car, run the following from a Command Line or PowerShell instance: wsl --unregister Legacy. You also have the option to manually remove the older legacy distribution by deleting the %localappdata%\lxss\ binder (and all it's sub-contents) using Windows File Explorer or with PowerShell: rm -Recurse $env:localappdata/lxss/.