Windows Subsystem for Linux

https://learn.microsoft.com/en-us/windows/wsl/
Admin
Windows Subsystem for Linux (WSL) enables developers to run a GNU/Linux environment directly on...
Tokens:126,437
Snippets:1,210
Trust Score:10
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Install distribution with Add-AppxPackage

Source: https://learn.microsoft.com/en-us/windows/wsl/install-manual

Run this command in the directory containing the downloaded .appx or .AppxBundle file to install the distribution. Replace app_name.Appx with the actual file name. This command does not work on Server Core installations. After installation, double-click the appx file to start the distribution; wsl -l will not show it until then.

```powershell
Add-AppxPackage .\app_name.Appx

```

--------------------------------

### Example wsl.conf file with automount, network, interop, user, and boot settings

Source: https://learn.microsoft.com/en-us/windows/wsl/manage

Sample wsl.conf file for Ubuntu-20.04 at \\wsl.localhost\Ubuntu-20.04\etc\wsl.conf. Demonstrates automount, network, interop, user, and boot settings. Note that the boot command runs as root and starts the Docker service.

```bash
# Automatically mount Windows drive when the distribution is launched
[automount]

# Set to true will automount fixed drives (C:/ or D:/) with DrvFs under the root directory set above. Set to false means drives won't be mounted automatically, but need to be mounted manually or with fstab.
enabled=true

# Sets the directory where fixed drives will be automatically mounted. This example changes the mount location, so your C-drive would be /c, rather than the default /mnt/c.
root = /

# DrvFs-specific options can be specified.
options = "metadata,uid=1003,gid=1003,umask=077,fmask=11,case=off"

# Sets the `/etc/fstab` file to be processed when a WSL distribution is launched.
mountFsTab=true

# Network host settings that enable the DNS server used by WSL 2. This example changes the hostname, sets generateHosts to false, preventing WSL from the default behavior of auto-generating /etc/hosts, and sets generateResolvConf to false, preventing WSL from auto-generating /etc/resolv.conf, so that you can create your own (ie. nameserver 1.1.1.1).
[network]
hostname=DemoHost
generateHosts=false
generateResolvConf=false

# Set whether WSL supports interop processes like launching Windows apps and adding path variables. Setting these to false will block the launch of Windows processes and block adding $PATH environment variables.
[interop]
enabled=false
appendWindowsPath=false

# Set the user when launching a distribution with WSL.
[user]
default=DemoUser

# Set a command to run when a new WSL instance launches. This example starts the Docker container service.
[boot]
command=service docker start
```

--------------------------------

### Sample wsl --install commands for custom distributions

Source: https://learn.microsoft.com/en-us/windows/wsl/build-custom-distro

Sample install commands using the manifest. Installing by flavor name installs the default version, while specifying the version name installs that exact version.

```powershell
wsl --install my-distro # Installs 'my-distro-v3' since it's the default for 'my-distro' flavor
wsl --install my-distro-v3 # Installs 'my-distro-v3' explicitly
wsl --install my-distro-v2 # Installs 'my-distro-v2' explicitly

```

--------------------------------

### WSL configuration for systemd in /etc/wsl.conf

Source: https://learn.microsoft.com/en-us/windows/wsl/build-custom-distro

Example `/etc/wsl.conf` to set whether systemd starts by default. Set `boot.systemd` to `true` or `false`.

```bash
# /etc/wsl.conf

[boot]
systemd=true|false
```

--------------------------------

### Install VLC

Source: https://learn.microsoft.com/en-us/windows/wsl/tutorials/gui-apps

Installs VLC, a free and open-source multimedia player. Launch it with 'vlc'.

```bash
sudo apt install vlc -y

```

--------------------------------

### Install Docker engine in WSL

Source: https://learn.microsoft.com/en-us/windows/wsl/tutorials/gpu-compute

Installs the Docker engine directly in WSL and starts the Docker service. Run this if you are not using Docker Desktop.

```bash
curl https://get.docker.com | sh
sudo service docker start

```

--------------------------------

### Install GIMP

Source: https://learn.microsoft.com/en-us/windows/wsl/tutorials/gui-apps

Installs GIMP, a free and open-source raster graphics editor. Launch it with 'gimp'.

```bash
sudo apt install gimp -y

```

--------------------------------

### Install MySQL with sudo apt install mysql-server

Source: https://learn.microsoft.com/en-us/windows/wsl/tutorials/wsl-database

Installs the MySQL server package on Ubuntu.

```bash
sudo apt install mysql-server

```

--------------------------------

### Start MySQL server with sudo service mysql start

Source: https://learn.microsoft.com/en-us/windows/wsl/tutorials/wsl-database

Starts the MySQL server before running the security script.

```bash
sudo service mysql start

```

--------------------------------

### Install redis-server

Source: https://learn.microsoft.com/en-us/windows/wsl/tutorials/wsl-database

Installs the Redis server package on Ubuntu.

```bash
sudo apt install redis-server

```

--------------------------------

### Set up a default user in CentOS with wsl.conf

Source: https://learn.microsoft.com/en-us/windows/wsl/use-custom-distro

Sets up a default user for the imported CentOS distribution. Installs sudo and password tools, creates a user, adds it to the wheel group for sudo privileges, and writes the default user to /etc/wsl.conf. The example uses the username 'caloewen'.

```bash
yum update -y && yum install passwd sudo -y
myUsername=caloewen
adduser -G wheel $myUsername
echo -e "[user]\ndefault=$myUsername" >> /etc/wsl.conf
passwd $myUsername

```

--------------------------------

### Install PyTorch-DirectML

Source: https://learn.microsoft.com/en-us/windows/wsl/tutorials/gpu-compute

Installs PyTorch-DirectML. First installs required system libraries (libblas3, libomp5, liblapack3) via apt, then installs the torch-directml package via pip.

```bash
sudo apt install libblas3 libomp5 liblapack3
pip install torch-directml

```

--------------------------------

### Start service and open psql shell

Source: https://learn.microsoft.com/en-us/windows/wsl/tutorials/wsl-database

Starts the PostgreSQL service and connects to it, opening the psql shell as the postgres user.

```bash
sudo service postgresql start

```

```bash
sudo -u postgres psql

```

--------------------------------

### Start Redis server

Source: https://learn.microsoft.com/en-us/windows/wsl/tutorials/wsl-database

Starts the Redis server service.

```bash
sudo service redis-server start

```

--------------------------------

### Start PostgreSQL service

Source: https://learn.microsoft.com/en-us/windows/wsl/tutorials/wsl-database

Starts the PostgreSQL database service.

```bash
sudo service postgresql start

```

--------------------------------

### Install and import Microsoft.WSL.Containers in C#

Source: https://learn.microsoft.com/en-us/windows/wsl/wsl-container

Install the Microsoft.WSL.Containers NuGet package using the .NET CLI, then import the namespace in C# code.

```powershell
dotnet add package Microsoft.WSL.Containers
```

```csharp
using Microsoft.WSL.Containers;
```

--------------------------------

### Example manifest with default and non-default versions

Source: https://learn.microsoft.com/en-us/windows/wsl/build-custom-distro

Example manifest showing how the default entry is selected for a flavor. The 'Default' field determines which version is installed when using the flavor name.

```json
{
    "ModernDistributions": {
        "my-distro": [
            {
                "Name": "my-distro-v3",
                "Default": true,
                "FriendlyName": "My distribution version 3 (latest)"
                [...]
            },
            {
                "Name": "my-distro-v2",
                "Default": false,
                "FriendlyName": "My distribution version 2"
                [...]
            }
        ]
    }
}

```

--------------------------------

### Create container and run command (C#)

Source: https://learn.microsoft.com/en-us/windows/wsl/wsl-container

Creates a container with an init process that runs '/bin/echo Hello from WSL Container!', sets output mode to Event, subscribes to OutputReceived to print output, and starts the container.

```csharp
var initProcess = new ProcessSettings
{
    CmdLine = new[] { "/bin/echo", "Hello from WSL Container!" },
    OutputMode = ProcessOutputMode.Event
};

var containerSettings = new ContainerSettings("alpine:latest")
{
    Name = "hello-container",
    InitProcess = initProcess
};

var container = session.CreateContainer(containerSettings);

container.InitProcess.OutputReceived += data =>
    Console.Write(Encoding.UTF8.GetString(data));

container.Start();

```

--------------------------------

### Install wget and ca-certificates with sudo apt-get install

Source: https://learn.microsoft.com/en-us/windows/wsl/tutorials/wsl-vscode

Installs wget (to retrieve content from web servers) and ca-certificates (to allow SSL-based applications to check the authenticity of SSL connections) in Debian or Ubuntu WSL distributions. These libraries are required by the VS Code server to start up.

```bash
sudo apt-get install wget ca-certificates

```

--------------------------------

### Truncated WSL 2 output when starting distribution

Source: https://learn.microsoft.com/en-us/windows/wsl/troubleshooting

When starting WSL 2, if the display language is not English, you may see a truncated error text showing only 'WSL 2'. To resolve, install the kernel manually as described in the documentation.

```powershell
PS C:\> wsl.exe
WSL 2

```

--------------------------------

### Show available commands with ubuntu.exe /?

Source: https://learn.microsoft.com/en-us/windows/wsl/troubleshooting

Use the distribution executable with /? to see what commands are available for a particular distribution. This example uses Ubuntu.

```bash
C:\> ubuntu.exe /?
```

--------------------------------

### Create container and run command (C++)

Source: https://learn.microsoft.com/en-us/windows/wsl/wsl-container

Creates a container with an init process that runs '/bin/echo Hello from WSL Container!', sets output mode to Event, subscribes to OutputReceived to print output, and starts the container. Uses C++/WinRT and must run inside a coroutine.

```cpp
using namespace winrt::Windows::Foundation::Collections;

ProcessSettings initProcess;
initProcess.OutputMode(ProcessOutputMode::Event);

auto cmdLine = single_threaded_vector<hstring>();
cmdLine.Append(L"/bin/echo");
cmdLine.Append(L"Hello from WSL Container!");
initProcess.CmdLine(cmdLine);

ContainerSettings containerSettings{ L"alpine:latest" };
containerSettings.Name(L"hello-container");
containerSettings.InitProcess(initProcess);

auto container = session.CreateContainer(containerSettings);

container.InitProcess().OutputReceived([](auto const& data)
{
    std::string text(data.begin(), data.end());
    printf("%s", text.c_str());
});

container.Start();

```

--------------------------------

### Create Containerfile for Django app

Source: https://learn.microsoft.com/en-us/windows/wsl/tutorials/wsl-containers

A minimal Containerfile for the Django example that describes how to build the image. It installs dependencies from requirements.txt and runs the Django development server on port 8000.

```dockerfile
FROM python:3
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
EXPOSE 8000
CMD ["python", "manage.py", "runserver", "0.0.0.0:8000"]
```

--------------------------------

### Create file with touch

Source: https://learn.microsoft.com/en-us/windows/wsl/tutorials/linux

Creates a new empty file named hello_world.txt.

```bash
touch hello_world.txt

```

--------------------------------

### Create directory with mkdir

Source: https://learn.microsoft.com/en-us/windows/wsl/tutorials/linux

Creates a new directory named hello_world.

```bash
mkdir hello_world

```

--------------------------------

### Create a SQLite test database

Source: https://learn.microsoft.com/en-us/windows/wsl/tutorials/wsl-database

Creates a test database named 'example.db' and opens the SQLite prompt. The database is empty after creation; you can create a table with CREATE TABLE empty (kol INTEGER); and use .dbinfo ?DB? to see the database.

```bash
sqlite3 example.db

```

--------------------------------

### Install SQLite3 on WSL

Source: https://learn.microsoft.com/en-us/windows/wsl/tutorials/wsl-database

Steps to install SQLite3 on WSL (e.g., Ubuntu): update package lists, install sqlite3, and confirm the installation by checking the version.

```bash
sudo apt update

```

```bash
sudo apt install sqlite3

```

```bash
sqlite3 --version

```

--------------------------------

### Set up NVIDIA Container Toolkit repository

Source: https://learn.microsoft.com/en-us/windows/wsl/tutorials/gpu-compute

Sets up the stable repository for the NVIDIA Container Toolkit. Required before installing the NVIDIA runtime packages.

```bash
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-docker-keyring.gpg
curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-docker-keyring.gpg] https://#g' | sudo tee /etc/apt/sources.list.d/nvidia-docker.list

```

--------------------------------

### Install X11 apps

Source: https://learn.microsoft.com/en-us/windows/wsl/tutorials/gui-apps

Installs a collection of X11 apps including xclock, xcalc, xclipboard, and xev. Launch any tool by entering its name, e.g., 'xclock'.

```bash
sudo apt install x11-apps -y

```

--------------------------------

### Set default WSL version with wsl --set-default-version

Source: https://learn.microsoft.com/en-us/windows/wsl/basic-commands

Sets the default WSL version (1 or 2) for new Linux distribution installations. Replace `<Version>` with 1 or 2, for example `wsl --set-default-version 2`. WSL 2 requires Windows 11 or Windows 10 version 1903, build 18362 or later.

```powershell
wsl --set-default-version <Version>

```

--------------------------------

### Example .wslconfig file

Source: https://learn.microsoft.com/en-us/windows/wsl/manage

A sample .wslconfig file that demonstrates configuration options for WSL 2. It sets memory, processors, custom kernel paths, swap settings, and experimental features. The file path is %UserProfile%\.wslconfig.

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

# Limits VM memory to use no more than 4 GB, this can be set as whole numbers using GB or MB
memory=4GB

# Sets the VM to use two virtual processors
processors=2

# Specify a custom Linux kernel to use with your installed distros. The default kernel used can be found at https://github.com/microsoft/WSL2-Linux-Kernel
kernel=C:\\temp\\myCustomKernel

# Specify the modules VHD for the custom Linux kernel to use with your installed distros.
kernelModules=C:\\temp\\modules.vhdx

# Sets additional kernel parameters, in this case enabling older Linux base images such as Centos 6
kernelCommandLine = vsyscall=emulate

# Sets amount of swap storage space to 8GB, default is 25% of available RAM
swap=8GB

# Sets swapfile path location, default is %UserProfile%\AppData\Local\Temp\swap.vhdx
swapfile=C:\\temp\\wsl-swap.vhdx

# Turn on default connection to bind WSL 2 localhost to Windows localhost. Setting is ignored when networkingMode=mirrored
localhostforwarding=true

# Disables nested virtualization
nestedVirtualization=false

# Turns on output console showing contents of dmesg when opening a WSL 2 distro for debugging
debugConsole=true

# Sets the maximum number of crash dump files to retain (default is 10)
maxCrashDumpCount=10

# Enable experimental features
[experimental]
sparseVhd=true

```

--------------------------------

### Install a specific Linux distribution with wsl.exe --install -d

Source: https://learn.microsoft.com/en-us/windows/wsl/install

Use this command to install a specific Linux distribution instead of the default Ubuntu. Replace [Distro] with the name of the distribution you want to install.

```powershell
wsl.exe --install -d [Distro]

```

--------------------------------

### Sample /etc/wsl-distribution.conf

Source: https://learn.microsoft.com/en-us/windows/wsl/build-custom-distro

Sample configuration file for a WSL distribution. Defines the out-of-box experience (OOBE) command, default user UID and name, start menu shortcut settings, and Windows Terminal profile template. The OOBE command runs on first interactive shell launch; a non-zero exit prevents shell access.

```bash
# /etc/wsl-distribution.conf

[oobe]
command = /etc/oobe.sh
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

```

--------------------------------

### Output of wsl --manage resize

Source: https://learn.microsoft.com/en-us/windows/wsl/disk-space

Example output after running `wsl --manage` to resize the virtual disk. Shows successful completion of e2fsck and resize2fs operations.

```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.

```

--------------------------------

### Install WSL with wsl --install

Source: https://learn.microsoft.com/en-us/windows/wsl/install

Run this command in PowerShell as administrator to enable WSL features and install the default Ubuntu distribution. After running it, restart your machine. This command only works if WSL is not already installed.

```powershell
wsl --install

```

--------------------------------

### Install Gnome Text Editor

Source: https://learn.microsoft.com/en-us/windows/wsl/tutorials/gui-apps

Installs the Gnome Text Editor, the default text editor for the GNOME desktop environment. After installation, launch it with 'gnome-text-editor ~/.bashrc'.

```bash
sudo apt install gnome-text-editor -y

```

--------------------------------

### Enable startup commands in /etc/wsl.conf

Source: https://learn.microsoft.com/en-us/windows/wsl/release-notes

Add this section to /etc/wsl.conf to enable startup commands. The command value is a string that will be executed when the WSL instance starts.

```ini
[boot]
command=<string>

```

--------------------------------

### wsl --help

Source: https://learn.microsoft.com/en-us/windows/wsl/basic-commands

Displays a list of options and commands available with WSL.

```powershell
wsl --help

```
Tokens:
Raw