Main > Live (#2358)

* Clarify requirements for adding WSL distributions

Added eligibility criteria for WSL distributions to be listed in `wsl --install`.

* Minor wordsmithing

* Basic commands review, add Git Cred Mgr keyring issue link (#2285)

* Enhance WSL troubleshooting for network connectivity (#2356)

* Enhance WSL troubleshooting for network connectivity

Added troubleshooting tips for WSL network issues related to IPv6 and VPN connections.

* Fix warnings

update absolute link
add code tics to remove html warning

---------

Co-authored-by: Matt Wojciakowski <mattwoj@microsoft.com>

* Update case-sensitivity.md for default case option (#2344)

* Update case-sensitivity.md for default case option

case=off is the new default setting since Build 17763 (1809)
https://docs.microsoft.com/en-us/windows/wsl/release-notes#build-17763-1809

* case-sensitivity.md: Update broken fstab link

* connect-usb: ARM64 is now supported (#2330)

Update the connect-usb.md doc to reflect that ARM64 is now supported by USBIPD since v5.0.0.

* Add reference to --web-download if install process hangs at 0.0% (#2323)

Source: https://www.reddit.com/r/bashonubuntuonwindows/comments/1hlmm6r/windows_subsystem_and_ubuntu_stuck_at_00/

This fixed the aforementioned issue for me.

* Fix broken PostgreSQL extension link in WSL database tutorial (#2310) (#2311)

* Networking fix (#2302)

* Update install-on-server.md (#2299)

Fixing a typo to change "Not" to "Note"

---------

Co-authored-by: Craig Loewen <crloewen@microsoft.com>
Co-authored-by: Keith Horton <khorton@microsoft.com>
Co-authored-by: 谢致邦 (XIE Zhibang) <Yeking@Red54.com>
Co-authored-by: David Lechner <david@lechnology.com>
Co-authored-by: Ben Greer <ben@grinbeard.com>
Co-authored-by: Vaibhav Deokar <39976690+dev-ai-kar@users.noreply.github.com>
Co-authored-by: Chris Golden <4693287+crgolden@users.noreply.github.com>

Author: 8 people

WSL/basic-commands.md

@@ -1,7 +1,7 @@
 ---
 title: Basic commands for WSL
 description: Reference for the basic commands included with Windows Subsystem for Linux (WSL).
-ms.date: 11/28/2023
+ms.date: 07/31/2025
 ms.topic: article
 ---
 

WSL/build-custom-distro.md

@@ -1,7 +1,7 @@
 ---
 title: Build a Custom Linux Distro for WSL - Windows
 description: Learn how to create a custom Linux distribution for Windows Subsystem for Linux.
-ms.date: 02/05/2025
+ms.date: 09/12/2025
 ms.topic: how-to
 ---
 
@@ -263,9 +263,9 @@ wsl --install my-distro-v2 # Installs 'my-distro-v2' explicitly
 
 ## Adding your distribution to `wsl --install` for all WSL users
 
-To make your WSL distribution available to all users, open a pull request on the [WSL GitHub repository](https://github.com/microsoft/WSL) that modifies the [DistributionInfo.json](https://github.com/microsoft/WSL/blob/master/distributions/DistributionInfo.json) file to include your distribution information.
+In order for your distribution to be included in the list for the command: `wsl --list --online`, the distribution must meet the [Membership criteria](https://oss-security.openwall.org/wiki/mailing-lists/distros#membership-criteria) outlined in the distribution mailing list. This ensures that all listed distributions adhere to the necessary security standards.
 
-This pull request will be reviewed by the WSL team.
+If your distribution meets the criteria and you would like to add it to the `--install` list, submit a pull request on the WSL GitHub repository (https://github.com/microsoft/WSL) that updates the [DistributionInfo.json file](https://github.com/microsoft/WSL/blob/master/distributions/DistributionInfo.json) with your distribution's details. This pull request will be reviewed by the WSL team.
 
 ## Adding your distribution to `wsl --install` for your enterprise or business group
 

WSL/case-sensitivity.md

@@ -86,18 +86,18 @@ To configure the case sensitivity option in the `wsl.conf` file when mounting a
 4. If the `wsl.conf` file does not already exist, you can create it using: `sudo touch wsl.conf` or by running `sudo nano /etc/wsl.conf`, which will create the file upon saving from the Nano editor.
 5. The following options are available for you to add into your `wsl.conf` file:
 
-**Default setting: `dir` for enabling case sensitivity per directory.**
+**Default setting: `off` for case sensitivity unavailable (all directories on mounted NTFS drives will be case insensitive).**
 
 ```bash
 [automount]
-options = case = dir
+options = case = off
 ```
 
-**Case sensitivity unavailable (all directories on mounted NTFS drives will be case insensitive): `off`**
+**Enabling case sensitivity per directory: `dir`**
 
 ```bash
 [automount]
-options = case = off
+options = case = dir
 ```
 
 **Treat all directories on the (NTFS) drive as case sensitive: `force`**
@@ -112,7 +112,7 @@ This option is only supported for mounting drives on Linux distributions running
 You will need to restart WSL after making any changes to the `wsl.conf` file in order for those changes to take effect. You can restart WSL using the command: `wsl --shutdown`
 
 > [!TIP]
-> To mount a drive (which uses the DrvFs filesystem plugin to make the disk available under /mnt, such as /mnt/c, /mnt/d, etc) with a specific case sensitivity setting for ALL drives, use `/etc/wsl.conf` as described above. To set the default mount options for one specific drive, use the [`/etc/fstab` file](http://manpages.ubuntu.com/manpages/xenial/man5/fstab.5.html) to specify these options.
+> To mount a drive (which uses the DrvFs filesystem plugin to make the disk available under /mnt, such as /mnt/c, /mnt/d, etc) with a specific case sensitivity setting for ALL drives, use `/etc/wsl.conf` as described above. To set the default mount options for one specific drive, use the [`/etc/fstab` file](https://manpages.ubuntu.com/manpages/noble/en/man5/fstab.5.html) to specify these options.
 > For more WSL configuration options, see [Configure per distro launch settings with wslconf](./wsl-config.md).
 
 ### Changing the case sensitivity on a drive mounted to a WSL distribution

WSL/connect-usb.md

@@ -14,7 +14,7 @@ Setting up the USB/IP project on your Windows machine will enable common develop
 ## Prerequisites
 
 - Running Windows 11 (Build 22000 or later). *(Windows 10 support is possible, see note below).*
-- A machine with an x64 processor is required. (x86 and Arm64 are currently not supported with usbipd-win).
+- A machine with an x64 or ARM64 processor is required. (x86 is currently not supported with usbipd-win).
 - WSL is [installed and set up with the latest version](./install.md).
 - Linux distribution installed and [set to WSL 2](./basic-commands.md#set-wsl-version-to-1-or-2).
 
@@ -53,7 +53,7 @@ This will install:
 Before attaching your USB device, ensure that a WSL command line is open.  This will keep the WSL 2 lightweight VM active.
 
 > [!NOTE]
-> This doc assumes that you have [`usbipd-win 4.0.0` or higher installed](https://github.com/dorssel/usbipd-win/releases/latest)
+> This doc assumes that you have [`usbipd-win 5.0.0` or higher installed](https://github.com/dorssel/usbipd-win/releases/latest)
 
 1. List all of the USB devices connected to Windows by opening PowerShell in *administrator* mode and entering the following command. Once the devices are listed, select and copy the bus ID of the device you’d like to attach to WSL.
 

WSL/install-on-server.md

@@ -59,7 +59,7 @@ See the [Downloading distributions](./install-manual.md#downloading-distribution
 
 ### Extract and install a Linux distribution
 
-Now that you've downloaded a Linux distribution, in order to extract its contents and manually install, follow these steps. Not that you will be downloading an appx file that contains several appx files. In this example we will use debian.
+Now that you've downloaded a Linux distribution, in order to extract its contents and manually install, follow these steps. Note that you will be downloading an appx file that contains several appx files. In this example we will use debian.
 
 1. List the contents of the appx using tar.exe:
 

WSL/install.md

@@ -31,6 +31,7 @@ The first time you launch a newly installed Linux distribution, a console window
 
 > [!NOTE]
 > The above command only works if WSL is not installed at all. If you run `wsl --install` and see the WSL help text, please try running `wsl --list --online` to see a list of available distros and run `wsl --install -d <DistroName>` to install a distro.
+> If the install process hangs at 0.0%, run `wsl --install --web-download -d <DistroName>` to first download the distribution prior to installing.
 > To uninstall WSL, see [Uninstall legacy version of WSL](./troubleshooting.md#uninstall-legacy-version-of-wsl) or [unregister or uninstall a Linux distribution](./basic-commands.md#unregister-or-uninstall-a-linux-distribution).
 
 ## Change the default Linux distribution installed

WSL/networking.md

@@ -149,7 +149,7 @@ This new mode addresses networking issues seen with using a NAT (Network Address
 
 ## DNS Tunneling
 
-On machines running Windows 11 22H2 and higher, setting [`dnsTunneling=true` under `[wsl2]` in the `.wslconfig` file](./wsl-config.md#configuration-settings-for-wslconfig) has WSL use a virtualization feature to answer DNS requests from within WSL, instead of requesting them over a networking packet. This feature is aimed to improve compatibility with VPNs, and other complex networking set ups.
+On machines running Windows 11 22H2 and higher the `dnsTunneling` feature is on by default (which can be found [under `[wsl2]` in the `.wslconfig` file](./wsl-config.md#configuration-settings-for-wslconfig)) and it uses a virtualization feature to answer DNS requests from within WSL, instead of requesting them over a networking packet. This feature is aimed to improve compatibility with VPNs, and other complex networking set ups.
 
 ## Auto Proxy
 

WSL/troubleshooting.md

@@ -1,7 +1,7 @@
 ---
 title: Troubleshooting Windows Subsystem for Linux
 description: Provides detailed information about common errors and issues people run into while running Linux on the Windows Subsystem for Linux. 
-ms.date: 07/16/2025
+ms.date: 10/03/2025
 ms.topic: troubleshooting-general
 ---
 
@@ -237,6 +237,15 @@ You can confirm local rule merging's setting by following these steps:
 
 You can find instructions on how to change this Firewall setting in [Configure Hyper-V firewall](/windows/security/operating-system-security/network-security/windows-firewall/hyper-v-firewall).
 
+### WSL has no network connection when disabling IPv6
+
+If IPv6 is disabled using the registry value `HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Tcpip6\Parameters (REG_DWORD) DisabledComponents`, WSL network connectivity can fail.
+See [Guidance for configuring IPv6 in Windows for advanced users](/troubleshoot/windows-server/networking/configure-ipv6-in-windows).
+
+If IPv6 must be disabled on the host system, we recommend using Powershell to do so by directly removing the IPv6 protocol bindings. For example:
+`Disable-NetAdapterBinding -Name "<MyAdapter>" -ComponentID ms_tcpip[6]`.
+
+
 ### WSL has no network connectivity once connected to a VPN
 
 If after connecting to a VPN on Windows, bash loses network connectivity, try this workaround from within bash. This workaround will allow you to manually override the DNS resolution through `/etc/resolv.conf`.

WSL/tutorials/wsl-database.md

@@ -195,7 +195,7 @@ To see what user accounts have been created on your PostgreSQL installation, use
 
 For more about working with PostgreSQL databases, see the [PostgreSQL docs](https://www.postgresql.org/docs/current/tutorial-createdb.html).
 
-To work with PostgreSQL databases in VS Code, try the [PostgreSQL extension](https://marketplace.visualstudio.com/items?itemName=ms-ossdata.vscode-postgresql).
+To work with PostgreSQL databases in VS Code, try the [PostgreSQL extension](https://marketplace.visualstudio.com/items?itemName=ms-ossdata.vscode-pgsql).
 
 ## Install MongoDB
 

WSL/tutorials/wsl-git.md

@@ -1,7 +1,7 @@
 ---
 title: Get started using Git on WSL
 description: Learn how to set up Git for version control on the Windows Subsystem for Linux, along with Git Credential Manager.
-ms.date: 06/21/2023
+ms.date: 08/22/2025
 ms.topic: get-started
 ---
 
@@ -73,29 +73,20 @@ It is recommended to install the [latest Git for Windows](https://github.com/git
 
 If you have a reason not to install Git for Windows, you can install GCM as a Linux application directly in your WSL distribution, but note that doing so means GCM is running as a Linux application and cannot utilize the authentication or credential storage features of the host Windows operating system. See the GCM repo for instructions on how to [configure WSL without Git for Windows](https://github.com/GitCredentialManager/git-credential-manager/blob/main/docs/wsl.md#configuring-wsl-without-git-for-windows).
 
-To set up GCM for use with a WSL distribution, open your distribution and enter this command:
+### Commands to check and set up GCM for WSL
 
-If Git installed is >= v2.39.0
+If you have installed Git for Windows, GCM is already installed and configured. You can verify this by running the following command in a WSL distribution:
 
-```bash
-git config --global credential.helper "/mnt/c/Program\ Files/Git/mingw64/bin/git-credential-manager.exe"
-```
-
-else if Git installed is >= v2.36.1
-
-```bash
-git config --global credential.helper "/mnt/c/Program\ Files/Git/mingw64/libexec/git-core/git-credential-manager.exe"
-```
-
-else if Git installed is < v2.36.1 enter this command:
-
-```bash
-git config --global credential.helper "/mnt/c/Program\ Files/Git/mingw64/bin/git-credential-manager-core.exe"
+```powershell
+git --version; git credential-manager --version
 ```
 
 > [!NOTE]
 > Using GCM as a credential helper for a WSL Git installation means that any configuration set in WSL Git is NOT respected by GCM (by default). This is because GCM is running as a Windows application, and therefore will use the Git for Windows installation to query configuration. This means things like proxy settings for GCM need to be set in Git for Windows as well as WSL Git as they are stored in different files (`%UserProfile%\.gitconfig` vs `\\wsl$\distro\home\$USER\.gitconfig`). You can configure WSL so that GCM will use the WSL Git configuration, but this means that proxy settings will be unique to the specific WSL installation and not shared with others or the Windows host.
 
+> [!WARNING]
+> There is currently an [issue with using keyring in the GitHub CLI](https://github.com/cli/cli/issues/8954).
+
 ### Git with SSH
 
 Git Credential Manager only works with HTTP(S) remotes. You can still use Git with SSH: