WSL (Windows Subsystem for Linux)

Introduction

WSL (Windows Subsystem for Linux) is a feature that allows you to run a Linux environment directly on Windows. It enables the use of Linux command-line tools and applications on Windows without the need for dual-booting or traditional full-spec virtual machines.

Features of WSL's lightweight virtual machine

• Users do not need to be aware of the virtual machine: WSL is integrated with Windows, so you don't need to manually start or stop the VM.
• File system integration: Files can be easily exchanged between Windows and Linux.
• Automatic resource management: WSL uses memory and CPU as needed, unlike VMs with fixed allocations.
• Fast startup: Due to its lightweight VM nature, startup is fast.
• Integration with Windows: The file system is integrated with the host OS, Windows, allowing mutual access and editing of files.

Personally, I consider its lightweight nature to be the biggest advantage. It's easier and quicker to set up a Linux environment compared to building one with traditional virtual machines, so it should be very useful for development when a Linux environment is needed.

Installation

How to install Linux on Windows with WSL

Execute the following command from PowerShell.

wsl --install

Enter your username and password to complete the process. In the example below, korochin is entered as the username.

PS C:\hoge> wsl --install
Installing: Ubuntu
Ubuntu has been installed.
Launching Ubuntu...
Installing, this may take a few minutes...
Please create a default UNIX user account. The username does not need to match your Windows username.
For more information visit: https://aka.ms/wslusers
Enter new UNIX username: korochin
New password:
Retype new password:
passwd: password updated successfully
Installation successful!
To run a command as administrator (user "root"), use "sudo <command>".
See "man sudo_root" for details.

Welcome to Ubuntu 22.04.3 LTS (GNU/Linux 5.15.153.1-microsoft-standard-WSL2 x86_64)

 * Documentation: https://help.ubuntu.com
 * Management: https://landscape.canonical.com
 * Support: https://ubuntu.com/advantage


This message is shown once a day. To disable it please create the
/home/korochin/.hushlogin file.
korochin@koro-P6-I7G60:~$

WSL File System

WSL's Linux file system and the host OS's Windows file system are seamlessly integrated, allowing you to browse folders and files in the Linux file system with Windows Explorer and edit files with Windows applications. Additionally, access to the Windows file system from Linux is possible, with Windows drives mounted as /mnt/c/ and /mnt/d/.

You can view the entire Linux system's files from Windows Explorer at the following path:

\\wsl.localhost\Ubuntu

From within WSL, you can open the current directory in Windows Explorer using the following command:

explorer.exe .

The actual Linux file system is a single virtual disk file, which is created at the following path: (For the Ubuntu distribution created during the initial WSL installation)

%LOCALAPPDATA%\Packages\CanonicalGroupLimited.Ubuntu_79rhkp1fndgsc\LocalState\ext4.vhdx

Starting and Stopping Distributions

WSL Basic Commands

Checking installed distributions

If Windows is restarted, WSL's Linux will be stopped.

wsl --list --verbose

or

wsl -l -v

PS C:\hoge> wsl -l -v
  NAME              STATE           VERSION
  docker-desktop    Stopped         2
* Ubuntu            Stopped         2

The one marked with * is the "default distribution".

Running Linux distributions

wsl [--distribution, -d <distribution name>] [--user, -u <username>]

• --distribution, -d Runs the specified distribution.

• --user, -u Runs as the specified user.

Example:

wsl --distribution Ubuntu --user korochin

wsl -d Ubuntu -u korochin

Default User

If the username is omitted, it will run as the "default user". The default user is the user created when the distribution was first installed.

wsl -d Ubuntu

PS C:\hoge> wsl -d Ubuntu
korochin@koro-P6-I7G60:/mnt/c/hoge$ whoami
korochin

The default user is registered in the Windows Registry ¹. Instead of directly modifying the registry, you can change the default user by adding the following lines to /etc/wsl.conf, which is a better approach.

# /etc/wsl.conf
[user]
default=default_username

Default Distribution

If the distribution name is omitted, the default distribution will be executed.

wsl -u korochin

If both the username and distribution name are omitted, it will "start the default distribution with the default user".

wsl

To change the default distribution, use the following method:

wsl --set-default <distribution name>

Stopping Linux distributions

Use the following command to stop a distribution. The distribution name cannot be omitted.

wsl --terminate <distribution name>

PS C:\hoge> wsl --terminate Ubuntu
The operation completed successfully.
PS C:\hoge> wsl -l -v
  NAME              STATE           VERSION
* Ubuntu            Stopped         2
  docker-desktop    Stopped         2

The following command shuts down WSL. It terminates all running distributions and the WSL system.

wsl --shutdown

Managing Distributions

Installing Distributions

To install a new distribution, use the following command:

wsl --install <distribution> [--name <distribution name>] [--location <installation folder>]

Example:

wsl --install Ubuntu --name Ubuntu-hoge --location D:\wsl\ubuntu-hoge

A list of available distributions can be checked with wsl -l -o.

PS C:\hoge> wsl -l -o
The following is a list of valid distributions that can be installed.
Install using 'wsl.exe --install <Distro>'.

NAME FRIENDLY NAME
AlmaLinux-8 AlmaLinux OS 8
AlmaLinux-9 AlmaLinux OS 9
AlmaLinux-Kitten-10 AlmaLinux OS Kitten 10
AlmaLinux-10 AlmaLinux OS 10
Debian Debian GNU/Linux
FedoraLinux-42 Fedora Linux 42
SUSE-Linux-Enterprise-15-SP6 SUSE Linux Enterprise 15 SP6
SUSE-Linux-Enterprise-15-SP7 SUSE Linux Enterprise 15 SP7
Ubuntu Ubuntu
Ubuntu-24.04 Ubuntu 24.04 LTS
archlinux Arch Linux
kali-linux Kali Linux Rolling
openSUSE-Tumbleweed openSUSE Tumbleweed
openSUSE-Leap-16.0 openSUSE Leap 16.0
Ubuntu-20.04 Ubuntu 20.04 LTS
Ubuntu-22.04 Ubuntu 22.04 LTS
OracleLinux_7_9 Oracle Linux 7.9
OracleLinux_8_10 Oracle Linux 8.10
OracleLinux_9_5 Oracle Linux 9.5
openSUSE-Leap-15.6 openSUSE Leap 15.6

If --location is omitted, a folder with a GUID assigned to each distribution will be created under %LOCALAPPDATA%\wsl, and the distribution will be installed there. Since --install downloads the distribution every time, it is faster to use import (described later) if you want to create multiple identical environments.

Exporting Distributions

wsl --export <distribution> <filename> exports a distribution to a tar file.

wsl --export Ubuntu ubuntu.tar

Importing Distributions

Import a tar file to create a new distribution. The second argument of --import (the target folder for virtual disk creation) cannot be omitted.

wsl --import Ubuntu-2 D:\wsl\ubuntu-2 ubuntu.tar

Using the --vhd option, you can directly import a virtual disk file to create a new distribution. This method is faster than importing a tar file, so it is recommended if you want to duplicate a distribution.

wsl --import Ubuntu-3 D:\wsl\ubuntu-3 --vhd D:\wsl\ubuntu-2\ext4.vhdx

Removing Distributions

wsl --unregister <distribution name>

The distribution name cannot be omitted.

Application Examples

Creating a PostgreSQL Server

1Installing PostgreSQL

sudo apt update
sudo apt install postgresql
sudo service postgresql start

2Setting a password for the postgres user

Initially, the postgres database user does not have a password set. A password is required for external connections, so set one.

sudo -i -u postgres psql

ALTER USER postgres WITH PASSWORD '<password>';
\q

3Allowing external connections

Edit pg_hba.conf to configure the authentication method for external connections (scram-sha-256: password authentication). Add the following line to /etc/postgresql/16/main/pg_hba.conf. Note: This setting (0.0.0.0/0) applies to all addresses, so be careful.

host    all             all             0.0.0.0/0               scram-sha-256

Edit postgresql.conf to accept external connection requests. Add the following line to /etc/postgresql/16/main/postgresql.conf. Note: This setting allows connections from all addresses, so be careful.

listen_addresses = '*'

Restart the PostgreSQL server to apply the settings.

sudo systemctl restart postgresql

4Connection check

Check the IP address of the virtual machine.

ip addr

Example:

korochin@koro-P6-I7G60:/mnt/c/hoge$ ip addr
1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000
    link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
    inet 127.0.0.1/8 scope host lo
       valid_lft forever preferred_lft forever
    inet 10.255.255.254/32 brd 10.255.255.254 scope global lo
       valid_lft forever preferred_lft forever
    inet6 ::1/128 scope host
       valid_lft forever preferred_lft forever
2: eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc mq state UP group default qlen 1000
    link/ether 00:15:5d:25:a7:cd brd ff:ff:ff:ff:ff:ff
    inet 172.24.25.30/20 brd 172.24.31.255 scope global eth0
       valid_lft forever preferred_lft forever
    inet6 fe80::215:5dff:fe25:a7cd/64 scope link
       valid_lft forever preferred_lft forever

• lo: 10.255.255.254/32 This is a special address WSL uses for internal communication. It cannot be used as an IP address.
• eth0: 172.24.25.30/20 172.24.25.30 is the IP address of the virtual machine. This address may vary depending on the environment.

Let's try connecting by specifying the IP address.

sudo -i -u postgres psql -h 172.24.25.30 -U postgres

Enter the password to connect. Here, the password was set to postgres.

korochin@koro-P6-I7G60:/mnt/c/hoge$ sudo -i -u postgres psql -h 172.24.25.30 -U postgres
Password for user postgres:
psql (16.10 (Ubuntu 16.10-0ubuntu0.24.04.1))
SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, compression: off)
Type "help" for help.

postgres=#

If the postgres=# prompt appears, the connection is successful.

5Connecting from an external program

Connect to the PostgreSQL server from a C# program on the Windows host.

dotnet add package Npgsql

using Npgsql;

var connectionString = "Host=172.24.25.30;Port=5432;Username=postgres;Password=postgres;Database=hoge";
using var connection = new NpgsqlConnection(connectionString);
connection.Open();
connection.Close();

Creating an Oracle Server

The distribution used for verification was OracleLinux 9.x.

1Installing Podman

sudo dnf install -y podman

2Getting Oracle Database image

sudo podman pull container-registry.oracle.com/database/free:latest

3Starting the container

If the password is not strong enough, startup will fail. Here, the password was set to Ora23c#Hoge.

sudo podman run -d --name oracle23c \
  -p 1521:1521 \
  -e ORACLE_PWD=Ora23c#Hoge \
  -v oracle_data:/opt/oracle/oradata \
  container-registry.oracle.com/database/free:latest

4Checking Oracle startup

Enter the oracle23c container running with Podman using a bash shell.

podman exec -it oracle23c bash

Connect with sqlplus.

sqlplus system/Ora23c#Hoge@localhost:1521/FREE

If a prompt like the following appears, it's successful.

SQL*Plus: Release 23.0.0.0.0 - Production on Mon Oct 13 07:30:43 2025
Version 23.9.0.25.07

Copyright (c) 1982, 2025, Oracle. All rights reserved.

Last Successful login time: Mon Sep 22 2025 06:26:57 +00:00

Connected to:
Oracle Database 23ai Free Release 23.0.0.0.0 - Develop, Learn, and Run for Free
Version 23.9.0.25.07

SQL>

5Connecting from an external program

Connect to the Oracle server from a C# program on the Windows host.

dotnet add package Oracle.ManagedDataAccess.Core

using Oracle.ManagedDataAccess.Client;

var connectionString = "User Id=system;Password=Ora23c#Hoge;Data Source=172.24.25.30:1521/FREE;";
using var connection = new OracleConnection(connectionString);
connection.Open();
connection.Close();

References

Official: Windows Subsystem for Linux documentation