Main > Live

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: 11/19/2024
+ms.date: 02/05/2025
 ms.topic: article
 ---
 
@@ -49,9 +49,11 @@ defaultUid = 1000
 defaultName = my-distro
 
 [shortcut]
+enabled = true
 icon = /usr/lib/wsl/my-icon.ico
 
 [windowsterminal]
+enabled = true
 ProfileTemplate = /usr/lib/wsl/terminal-profile.json
 ```
 
@@ -63,6 +65,9 @@ WSL distribution file configuration options:
 | `oobe.defaultUid` | integer | `<none>` | The default UID that the distribution starts with. This is useful when the `oobe.command` script creates a new user. |
 | `oobe.defaultName`| string | `<none>` | The default name that the distribution is registered under. This default name can be replaced with the command: `wsl.exe --install <distro> --name <name>` |
 | `shortcut.icon` | string | The default WSL icon | The icon in the start menu shortcut for the distribution. Must be in `.ico` format with a maximum size of `10MB` |
+| `shortcut.enabled` | boolean | true | Whether a start menu shortcut should be created when the distribution is installed. |
+| `windowsterminal.profileTemplate` | string | `<none>` | The JSON template to generate a Windows Terminal profile for this distribution. |
+| `windowsterminal.enabled` | boolean | true | Whether a terminal profile should be created when the distribution is installed. If `profileTemplate` is not set, a default profile will be generated. | 
 | `windowsterminal.profileTemplate` | string | Path to a terminal template file | The JSON template to generate a Windows Terminal profile for this distribution. | 
 
 You need to create an out of box experience (OOBE) first run experience for the distribution. Below is a sample bash script that you can use. This script assumes that `oobe.defaultUid` is set to `1000`: 

WSL/compare-versions.md

@@ -54,25 +54,25 @@ WSL 2 provides the benefits of WSL 1, including seamless integration between Win
 
 ### Full Linux kernel
 
-The Linux kernel in WSL 2 is built by Microsoft from the latest stable branch, based on the source available at kernel.org. This kernel has been specially tuned for WSL 2, optimizing for size and performance to provide an amazing Linux experience on Windows. The kernel will be serviced by Windows updates, which means you will get the latest security fixes and kernel improvements without needing to manage it yourself.
+The Linux kernel in WSL 2 is built by Microsoft from the latest stable branch, based on the source available at [kernel.org](https://kernel.org). This kernel has been specially tuned for WSL 2, optimizing for size and performance to provide an amazing Linux experience on Windows. The kernel will be serviced by Windows updates, which means you will get the latest security fixes and kernel improvements without needing to manage it yourself.
 
 The [WSL 2 Linux kernel is open source](https://github.com/microsoft/WSL2-Linux-Kernel). If you'd like to learn more, check out the blog post [Shipping a Linux Kernel with Windows](https://devblogs.microsoft.com/commandline/shipping-a-linux-kernel-with-windows/) written by the team that built it.
 
 Learn more in the [Release Notes for Windows Subsystem for Linux kernel](./kernel-release-notes.md).
 
 ### Increased file IO performance
 
-File intensive operations like git clone, npm install, apt update, apt upgrade, and more are all noticeably faster with WSL 2.
+File intensive operations like `git clone`, `npm install`, `apt update`, `apt upgrade`, and more are all noticeably faster with WSL 2.
 
-The actual speed increase will depend on which app you're running and how it is interacting with the file system. Initial versions of WSL 2 run up to 20x faster compared to WSL 1 when unpacking a zipped tarball, and around 2-5x faster when using git clone, npm install and cmake on various projects.
+The actual speed increase will depend on which app you're running and how it is interacting with the file system. Initial versions of WSL 2 run up to 20x faster compared to WSL 1 when unpacking a zipped tarball, and around 2-5x faster when using `git clone`, `npm install` and `cmake` on various projects.
 
 ### Full system call compatibility
 
 Linux binaries use system calls to perform functions such as accessing files, requesting memory, creating processes, and more. Whereas WSL 1 used a translation layer that was built by the WSL team, WSL 2 includes its own Linux kernel with full system call compatibility. Benefits include:
 
 - A whole new set of apps that you can run inside of WSL, such as **[Docker](tutorials/wsl-containers.md)** and more.
 
-- Any updates to the Linux kernel are immediately ready for use. (You don't have to wait for the WSL team to implement updates and add the changes).
+- Any updates to the Linux kernel are immediately ready for use (you don't have to wait for the WSL team to implement updates and add the changes).
 
 ## Exceptions for using WSL 1 rather than WSL 2
 
@@ -82,21 +82,21 @@ We recommend that you use WSL 2 as it offers faster performance and 100% system
   - If you will be using your WSL Linux distribution to access project files on the Windows file system, and these files cannot be stored on the Linux file system, you will achieve faster performance across the OS files systems by using WSL 1.
 - A project which requires cross-compilation using both Windows and Linux tools on the same files.
   - File performance across the Windows and Linux operating systems is faster in WSL 1 than WSL 2, so if you are using Windows applications to access Linux files, you will currently achieve faster performance with WSL 1.
-- Your project needs access to a serial port or USB device. *However,* USB device support is now available for WSL 2 via the USBIPD-WIN project. See [Connect USB devices](./connect-usb.md) for set up steps.
+- Your project needs access to a serial port or USB device. *However,* USB device support is now available for WSL 2 via the `USBIPD-WIN` project. See [Connect USB devices](./connect-usb.md) for set up steps.
 - WSL 2 does not include support for accessing serial ports. Learn more in the [FAQs](./faq.yml#can-i-access-the-gpu-in-wsl-2--are-there-plans-to-increase-hardware-support-) or in [WSL GitHub repo issue on serial support](https://github.com/microsoft/WSL/issues/4322).
 - You have strict memory requirements
   - WSL 2's memory usage grows and shrinks as you use it. When a process frees memory this is automatically returned to Windows. However, as of right now WSL 2 does not yet release cached pages in memory back to Windows until the WSL instance is shut down. If you have long running WSL sessions, or access a very large amount of files, this cache can take up memory on Windows. We are tracking the work to improve this experience on [the WSL GitHub repository issue 4166](https://github.com/microsoft/WSL/issues/4166).
 - For those using VirtualBox, be sure to use the latest version of both VirtualBox and WSL 2. See the [related FAQ](./faq.yml#will-i-be-able-to-run-wsl-2-and-other-3rd-party-virtualization-tools-such-as-vmware--or-virtualbox-). 
-- If you rely on a Linux distribution to have an IP address in the same network as your host machine, you may need to set up a workaround in order to run WSL 2. WSL 2 is running as a hyper-v virtual machine. This is a change from the bridged network adapter used in WSL 1, meaning that WSL 2 uses a Network Address Translation (NAT) service for its virtual network, instead of making it bridged to the host Network Interface Card (NIC) resulting in a unique IP address that will change on restart. To learn more about the issue and workaround that forwards TCP ports of WSL 2 services to the host OS, see [WSL GitHub repository issue 4150, NIC Bridge mode (TCP Workaround)](https://github.com/microsoft/WSL/issues/4150).
+- If you rely on a Linux distribution to have an IP address in the same network as your host machine, you may need to set up a workaround in order to run WSL 2. WSL 2 is running as a Hyper-V virtual machine. This is a change from the bridged network adapter used in WSL 1, meaning that WSL 2 uses a Network Address Translation (NAT) service for its virtual network, instead of making it bridged to the host Network Interface Card (NIC) resulting in a unique IP address that will change on restart. To learn more about the issue and workaround that forwards TCP ports of WSL 2 services to the host OS, see [WSL GitHub repository issue 4150, NIC Bridge mode (TCP Workaround)](https://github.com/microsoft/WSL/issues/4150).
 
 > [!NOTE]
 > Consider trying the VS Code [Remote WSL Extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-wsl) to enable you to store your project files on the Linux file system, using Linux command line tools, but also using VS Code on Windows to author, edit, debug, or run your project in an internet browser without any of the performance slow-downs associated with working across the Linux and Windows file systems. [Learn more](tutorials/wsl-vscode.md).
 
 ## WSL in the Microsoft Store
 
-WSL has lifted the update functionality out of the Windows OS Image into a package that is available via the Microsoft Store. This means faster updates and servicing as soon as they're available, rather than needing to wait for an update of your Windows operating system.
+WSL has lifted the update functionality out of the Windows OS image into a package that is available via the Microsoft Store. This means faster updates and servicing as soon as they're available, rather than needing to wait for an update of your Windows operating system.
 
-WSL was originally included in the Windows operating system as an optional component that need to be enabled in order to install a Linux distribution. WSL in the Store has the same user experience, and is the same product, but receives updates and servicing as a store package, rather than as an entire OS update. Beginning in Windows version 19044 or higher, running the `wsl.exe --install` command will install the WSL servicing update from the Microsoft Store. ([See the blog post announcing this update](https://devblogs.microsoft.com/commandline/the-windows-subsystem-for-linux-in-the-microsoft-store-is-now-generally-available-on-windows-10-and-11/)). If you are already using WSL, you can update to ensure that you're receiving the latest WSL features and servicing from the store by running `wsl.exe --update`.
+WSL was originally included in the Windows operating system as an optional component that need to be enabled in order to install a Linux distribution. WSL in the Store has the same user experience, and is the same product, but receives updates and servicing as a store package, rather than as an entire OS update. Beginning in Windows version 19044 or higher, running the `wsl.exe --install` command will install the WSL servicing update from the Microsoft Store. ([See the blog post announcing this update](https://devblogs.microsoft.com/commandline/the-windows-subsystem-for-linux-in-the-microsoft-store-is-now-generally-available-on-windows-10-and-11)). If you are already using WSL, you can update to ensure that you're receiving the latest WSL features and servicing from the store by running `wsl.exe --update`.
 
 > [!NOTE]
 > If the Microsoft Store is inaccessible within your organization, you can still utilize this WSL version by appending `--web-download` to the `--update` command, such as `wsl --update --web-download`. You need to manually update WSL every time a new release becomes available using this method.

WSL/disk-space.md

@@ -1,7 +1,7 @@
 ---
 title: How to manage WSL disk space
 description: Learn how to check the amount of disk space available, expand the size of the Virtual Hard Disk (VHD), repair a VHD mounting or read-only error, and locate the .vhdx file and disk path for Linux distributions installed with WSL 2.
-ms.date: 11/19/2024
+ms.date: 02/05/2025
 ms.topic: article
 ---
 
@@ -45,7 +45,32 @@ If you see that you are near to reaching the available amount of disk space allo
 
 ## How to expand the size of your WSL 2 Virtual Hard Disk
 
-To expand the VHD size for a Linux distribution beyond the **default 1TB maximum** amount of allocated disk space, follow the steps below. *(For earlier WSL releases that have not yet been updated, this max default may be set to 512GB or 256GB).*
+To expand the VHD size for a Linux distribution beyond the default 1TB maximum amount of allocated disk space, you can use the `wsl --manage` command or follow the manual steps below. (Earlier WSL releases max default may be set to 512GB or 256GB).
+
+### Expand VHD size using `wsl --manage`
+
+The `wsl --manage` command is only available to WSL releases 2.5 and higher.
+
+To resize the allocated space on your virtual disk:
+
+1. Terminate all WSL instances using the command `wsl.exe --shutdown`
+
+2. Run `wsl --manage <distribution name> --resize <memory string>`. Supported memory strings are of the form `<Memory Value>B/M/MB/G/GB/T/TB`. Decimal values are currently unsupported (e.g. `2.5TB`).
+
+Output should look similar to the following:
+
+```bash
+e2fsck 1.46.5 (30-Dec-2021)
+Pass 1: Checking inodes, blocks, and sizes
+resize2fs 1.46.5 (30-Dec-2021)
+The operation completed successfully.
+```
+
+The virtual drive (ext4.vhdx) for this Linux distribution has now successfully been expanded to the new size.
+
+### Manual expansion
+
+To expand the VHD size for a Linux distribution using manual steps:
 
 1. Terminate all WSL instances using the command: `wsl.exe --shutdown`
 
@@ -112,7 +137,7 @@ old_desc_blocks = 32, new_desc_blocks = 38
 The filesystem on /dev/sdb is now 78643200 (4k) blocks long.
 ```
 
-The virtual drive (ext4.vhdx) for this Linux distribution has now successfully been expanded to the new size.  
+The virtual drive (ext4.vhdx) for this Linux distribution has now successfully been expanded to the new size.
 
 > [!IMPORTANT]
 > We recommend that you do not modify, move, or access the WSL related files located inside of your `AppData` folder using Windows tools or editors. Doing so could cause your Linux distribution to become corrupted. If you would like to access your Linux files from Windows, that is possible via the path `\\wsl$\<distribution-name>\`. Open your WSL distribution and enter `explorer.exe .` to view that folder. To learn more, see the blog post: [Accessing Linux files from Windows](https://devblogs.microsoft.com/commandline/whats-new-for-wsl-in-windows-10-version-1903/#accessing-linux-files-from-windows).

WSL/docfx.json

@@ -51,7 +51,10 @@
       "ms.author": "mattwoj",
       "ms.reviewer": "crloewen",
       "searchScope": ["WSL"],
-      "adobe-target": true
+      "adobe-target": true,
+      "contributors_to_exclude": [
+      "VSC-Service-Account"
+      ]
     },
     "contributors_to_exclude": [
       "VSC-Service-Account"

WSL/networking.md

@@ -64,7 +64,10 @@ If you are building a networking app (for example an app running on a NodeJS or
 
 If you want to access a networking app running on Windows (for example an app running on a NodeJS or SQL server) from your Linux distribution (ie Ubuntu), then you need to use the IP address of your host machine. While this is not a common scenario, you can follow these steps to make it work.
 
-1. Obtain the IP address of your host machine by running this command from your Linux distribution: `ip route show | grep -i default | awk '{ print $3}'`
+1. Obtain the IP address of your host machine by running this command from your Linux distribution: 
+```bash
+ip route show | grep -i default | awk '{ print $3}'`
+```
 2. Connect to any Windows server using the copied IP address.
 
 The picture below shows an example of this by connecting to a Node.js server running in Windows via curl.

WSL/systemd.md

@@ -1,7 +1,7 @@
 ---
 title: Use systemd to manage Linux services with WSL
 description: Learn how to use systemd to manage Linux services with Windows Subsystem for Linux.
-ms.date: 07/17/2024
+ms.date: 01/13/2025
 ms.topic: article
 ---
 
@@ -25,7 +25,10 @@ Systemd is [now the default for the current version of Ubuntu](https://canonical
 
 To enable systemd for any other Linux distributions running on WSL 2 (changing the default from using the systemv init):
 
-1. Ensure that your WSL version is 0.67.6 or newer. (To check, run `wsl --version`. To update, run `wsl --update` or [download the latest version from the Microsoft Store](https://aka.ms/wslstorepage).)
+1. Ensure that your WSL version is 0.67.6 or newer:
+
+    - to check, run `wsl --version`; if the command throws `Invalid command line option: --version` error, you must update WSL;
+    - to update, run `wsl --update` or [download the latest version from the Microsoft Store](https://aka.ms/wslstorepage).
 
 2. Open a command line for your Linux distribution and enter `cd /` to access the root directory, then `ls` to list the files. You will see a directory named "etc" that contains the WSL configuration file for the distribution. Open this file so that you can make an update with the Nano text editor by entering: `nano /etc/wsl.conf`.
 
@@ -36,11 +39,19 @@ To enable systemd for any other Linux distributions running on WSL 2 (changing t
     systemd=true
     ```
 
-4. Exit the Nano text editor (Ctrl + X, select Y to save your change). You will then need to close the Linux distribution. You can use the command `wsl.exe --shutdown` in PowerShell to restart all WSL instances.
+    ![Enable systemd on WSL 2](media/systemd-enable.png)
+
+4. Exit the Nano text editor (Ctrl + X, type Y to save your change and confirm with the `enter` key).
+
+5. You will then need to close the Linux distribution. You can use the command `wsl.exe --shutdown` in PowerShell to restart all WSL instances.
+
+6. Once you restart the Linux distribution, systemd will be running. You can verify it by using the command `systemctl status` to show the _running_ state and the command `systemctl list-unit-files --type=service`, which will show the status of any services associated with your Linux distribution. 
 
-![Enable systemd on WSL 2](media/systemd-enable.png)
+If your Linux distribution is Debian/Ubuntu/Kali Rolling, you should not only have installed the systemd package, but also make sure the systemd-sysv package is installed.
 
-Once your Linux distribution restarts, systemd will be running. You can confirm using the command: `systemctl list-unit-files --type=service`, which will show the status of any services associated with your Linux distribution.
+```bash
+sudo apt-get update -y && sudo apt-get install systemd systemd-sysv -y
+```
 
 Learn more about [Advanced settings configuration in WSL](wsl-config.md), including the difference between the `wsl.conf` (distribution-specific) and `.wslconfig` (global) config files, how to update automount settings, etc.
 

WSL/troubleshooting.md

@@ -63,7 +63,7 @@ You can also:
   3. The WSL executable is only installed to the native system directory. When you’re running a 32-bit process on 64-bit Windows (or on ARM64, any non-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 folder: `\Windows\sysnative`. It won’t actually be present on disk, mind you, but the filesystem path resolver will find it.
 
 - **Error: 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 be enabled first. If it fails, it you will see the message: `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 be enabled first. If it fails, you will see the message: `This update only applies to machines with the Windows Subsystem for Linux`.
   - There are three possible reason you see this message:
 
   1. You are still in old version of Windows which doesn't support WSL 2. See step #2 for version requirements and links to update.