Troubleshooting#

Installation#

Installer fails#

Installation failures can be caused by the following:

  • Windows 11 has pending required updates.

    Run Windows Update and install all required updates. Then try running the installer again.

  • You are being rate limited by GitHub.

    WSL is downloaded and updated directly from GitHub. If you are on a shared network where users access GitHub with unregistered accounts, you may run into a rate limiter. To verify, run the following command and check that there are remaining credits in the core section of the output:

    curl https://api.github.com/rate_limit

    "resources": {
  "core": {
    "limit": 60,
    "remaining": 0,
    "reset": 1741626149,
    "used": 1,
    "resource": "core"
  },

    If there are no credits remaining, you need to wait and try again after about one hour or relocate the computer to a non-shared network with remaining GitHub API credits.

Installer freezes or hangs for an indefinite amount of time#

  1. Check if the installer is frozen due to one of the following reasons:

    • Checking for an internet connection

    • Updating software components inside the WSL2 distribution

    • Showing an unhandled exception message on the installer screen

  2. Kill the installer process from Task Manager.

  3. Reboot the system and run the installer again.

Installer fails to configure WSL2 or fails to import the distribution#

  1. Check for pending Windows updates and reboot your computer if necessary.

  2. Run wsl --update manually in Windows PowerShell. If your internet connection is unstable, you may need to run this command multiple times.

  3. If you have an old version of WSL, manually install WSL2.

  4. Reboot the system and run the installer again.

Installer fails to configure the distribution#

  1. Run wsl -l in Command Prompt and check if the NVIDIA-Workbench distribution is listed.

  2. Run wsl  --update in Command Prompt and make sure WSL2 is updated to the latest version

  3. Run wsl  --unregister NVIDIA-Workbench in Command Prompt to unregister the distribution.

  4. Reboot the system and run the installer again.

WSL2 configuration#

I need to change a WSL2 installation#

You can set a WSL2 configuration in the following ways:

  • Edit the .wslconfig file for all WSL2 distributions, per user. Locate this file in the C:\Users\<username> directory. If the file is not present in this location, create a new text file named .wslconfig to customize all of your WSL2 installations.

  • Edit the /etc/wsl.config file for distribution-specific settings.

For more information, see the Microsoft documentation.

System RAM and disk space#

I need to modify the amount of system RAM available for WSL2 use#

Add the following to the WSL2 configuration (.wslconfig file):

# Settings apply across all Linux distros running on WSL 2.
[wsl2]

# Limits VM memory to use no more than 32 GB. This can be set as whole numbers
# using GB or MB. On windows, the default is 50% of available SRAM.
memory = 32GB

This allows the WSL2 instance to utilize up to the specified memory size.

WSL2 is not able to use more than 50% of available SRAM#

By default, WSL2 uses 50% of available SRAM. This limit can be changed by adding the following configuration in the .wslconfig file:

# Settings apply across all Linux distros running on WSL 2.
[wsl2]

# Limits VM memory to use no more than 32 GB. This can be set as whole numbers
# using GB or MB. On windows, the default is 50% of available SRAM.
memory = 32GB

For more information, see Advanced settings configuration in WSL.

Upon loading a NIM, the WSL2 instance uses too much memory#

Use any of the following options to reduce system memory utilization inside WSL2. These commands require sudo access to the distributions.

  • Set "autoMemoryReclaim=dropcache" in the WSL2 configuration. This setting automatically releases cached memory after detecting idle CPU usage. Set to gradual for slow release; it waits for around 5 minutes with no CPU activity and then releases the caches. Set to dropcache to instantly release cached memory.

  • If you need to explicitly clear caches within the WSL2 distribution, run the following command in PowerShell:

    wsl -d NVIDIA-Workbench -u root
echo 1 > /proc/sys/vm/drop_caches
// NVIDIA-Workbench is the distribution name from NIM Installer

  • Run the following command with sudo privileges within the WSL2 distribution:

    sudo sh -c 'echo 1 > /proc/sys/vm/drop_caches'`

Disk space isn’t restored after I uninstall a NIM#

WSL2 doesn’t automatically release file storage, even after deleting the files from the distribution. Therefore, vhdx size on disk keeps increasing. After setting sparseVhd=true, any new VHD is set to sparse automatically. To reduce the size of existing VHDs, use the DiskPart utility:

diskpart
select vdisk file="<path-to-vhdx>"
compact vdisk
exit

Errors and timeouts#

TLS issues within WSL2#

TLS-related timeouts and errors could be related to the MTU size. For more information, see a related GitHub issue. You can try running the following commands:

sudo ip link set dev eth0 mtu 1350
ip link list
On this page