DOCSEARCHbyAlgolia
Submit Docs

Windows Subsystem for Linux (WSL) Documentation

repository·main·Indexed 25 days ago

https://github.com/microsoftdocs/wsl

Official guides and technical references for Windows Subsystem for Linux (WSL). Includes instructions for installing Linux distributions, managing WSL 1 and WSL 2 architectures, using the wsl command-line tool for distribution management and disk mounting, and building custom Linux distributions with OOBE scripts and configuration files.

Tokens
39.2K
Snippets
99
Records
237
Agent score
80%

What's inside WSL

  1. What is Windows Subsystem for Linux (WSL)?

    main

    Windows Subsystem for Linux (WSL) is a Windows feature that enables running a Linux environment directly on a Windows machine without the overhead of a separate virtual machine or dual-booting. It allows developers to use Windows and Linux tools simultaneously in a seamless workflow.

    Key Capabilities:

    • Run Linux Distributions: Install and run distributions like Ubuntu, Debian, and Kali via the Microsoft Store, or import/build custom distributions.
    • Linux Tooling: Run BASH, command-line tools (grep, sed, awk), and ELF-64 binaries.
    • Development Environments: Run languages (NodeJS, Python, Ruby, C/C++, C#, Rust, Go, etc.), editors (vim, emacs, tmux), and services (SSHD, MySQL, Apache, MongoDB, PostgreSQL).
    • Cross-Platform Integration: Invoke Windows applications from a Unix-like shell and run GNU/Linux applications on Windows.
    • GUI and Hardware Acceleration: Run Linux graphical applications integrated into the Windows desktop and use your device GPU to accelerate Machine Learning workloads running on Linux.

  2. Access WSL documentation and release notes

    main
    The official rendered documentation for Windows Subsystem for Linux (WSL) and its release notes are hosted on the Microsoft Learn website. Use these links for the most up-to-date guides and version information.

  3. Overview of WSL architecture and components

    main

    WSL is composed of several distribution components that run either in Windows or inside the WSL 2 virtual machine. The architecture is divided into the following main areas:

    Windows-side components

    • Command line executables: The primary entry points for interacting with WSL. These include wsl.exe, wslconfig.exe, and wslg.exe. These processes are typically run from C:\Windows\System32\.
    • WSL service: wslservice.exe is responsible for starting the WSL Virtual Machine (VM), starting installed Linux distributions, and mounting file access shares.

    Linux-side components

    • Linux init and daemon processes: Binaries running inside Linux to provide core functionality. This includes init for startup, gns for networking, and localhost for port forwarding.
    • File sharing: The plan9 server implementation is used to share Linux files with Windows.

    Open Source Sub-projects

    • WSLg: Provides support for Wayland and X server scenarios, enabling Linux GUI applications to run in Windows.
    • WSL2-Linux-Kernel: The source code for the specific Linux kernel used by WSL 2.

  4. Understand Windows file system access security in WSL

    main

    When a Linux binary inside WSL accesses a Windows file, it operates using the permissions of the Windows user who executed wsl.exe.

    Key Security Behaviors:

    • Permission Parity: Even if a user has root access inside the WSL distribution, they cannot perform Windows administrator-level operations on the Windows host unless the Windows user running WSL has those permissions.
    • Execution Level: Running a shell like bash within WSL carries the same security level and permissions as running powershell from Windows for that specific user.

  5. Enable Mirrored mode networking in WSL

    main

    On Windows 11 22H2 and higher, you can enable Mirrored mode to improve networking compatibility. This mode 'mirrors' Windows network interfaces into Linux, providing several benefits:

    • IPv6 support
    • Localhost connectivity: Connect to Windows servers from Linux using 127.0.0.1 (Note: IPv6 ::1 is not supported).
    • VPN compatibility: Improved networking for VPN environments.
    • Multicast support
    • LAN access: Connect to WSL directly from your local area network.

    To enable this, add networkingMode=mirrored under the [wsl2] section of your .wslconfig file.

  6. Compare WSL 1 and WSL 2 features

    main

    WSL 2 is the current default version and uses a managed, lightweight utility virtual machine (VM) running a real Linux kernel. WSL 1 uses a translation layer.

    Key Differences:

    • WSL 2 Advantages: Includes a full Linux kernel, full system call compatibility (enabling apps like Docker), systemd support, and significantly faster file I/O performance for Linux-native operations (e.g., git clone, npm install).
    • WSL 1 Advantages: Better performance when accessing files stored on the Windows file system. WSL 1 also runs more reliably with certain third-party virtualization tools like VirtualBox.
    • Commonalities: Both support fast boot times, small resource footprints, Windows/Linux integration, and IPv6 support.

  7. How systemd affects WSL architecture

    main

    Enabling systemd changes the process hierarchy within WSL. Because systemd must run as PID 1, the standard WSL init process becomes a child process of systemd.

    Key architectural implications:

    • Shutdown Control: Shutdown sequences are now controlled by systemd.
    • WSLg Compatibility: The architecture has been modified to maintain compatibility with WSLg (the component for running Linux GUI applications).
    • Instance Lifecycle: Enabling systemd does not change how WSL instances stay alive. systemd services will not keep a WSL instance running in the background; the instance lifecycle still follows the standard WSL background task behavior.

  8. Understand the Linux user space for WSL plugins

    main

    Linux processes created via ExecuteBinary() run in the root namespace of the WSL2 Virtual Machine.

    Key characteristics of this namespace:

    • It is not associated with any specific distribution.
    • It uses a minimal Mariner-based root file system.
    • The file system is a writable tmpfs, meaning all changes are lost when the WSL2 Virtual Machine shuts down.

    To inspect the content of this root namespace, run:

    wsl --debug-shell

    Note: The WSL instance must be running to use this command.

    wsl --debug-shell

  9. Understand the difference between .wslconfig and wsl.conf

    main

    WSL uses two distinct configuration files to manage settings. The choice between them depends on whether you want to apply settings globally to the entire WSL environment or specifically to a single Linux distribution.

    .wslconfig (Global Settings)

    • Scope: Applies to all WSL distributions.
    • Purpose: Configures WSL features and the virtual machine powering WSL 2 (e.g., RAM, CPU count, kernel selection).
    • Location: %UserProfile%\.wslconfig (located in your Windows user profile folder, outside of any Linux distribution).
    • Compatibility: Currently applies only to WSL 2 distributions.

    wsl.conf (Per-Distribution Settings)

    • Scope: Applies only to the specific distribution where the file exists.
    • Purpose: Configures distribution-specific behavior such as systemd support, automount settings, networking, interoperability, and the default user.
    • Location: /etc/wsl.conf (located inside the Linux distribution's file system).

  10. Understand the WSL 2 kernel delivery and lifecycle

    main

    WSL 2 distributions use a full Linux kernel that is open source. The source code is maintained in the WSL2-Linux-Kernel repository.

    Key delivery details:

    • Delivery Method: The kernel is delivered to your machine via Microsoft Update.
    • Release Schedule: The kernel follows a separate release schedule from the Windows Subsystem for Linux itself (which is delivered as part of the Windows image).

  11. How VS Code extensions work in a WSL environment

    main

    The WSL extension uses a client-server architecture:

    • Client (Windows): Runs the user interface (UI).
    • Server (WSL): Runs your code, Git, and language-specific plugins (e.g., Python, linting, debugging tools).

    Managing Extensions

    When you open the 'Extensions' tab in VS Code, you will see two categories:

    1. Local Extensions: Installed on Windows (e.g., UI themes).
    2. WSL Extensions: Installed in the WSL distribution (e.g., Python, C++, debuggers).

    If an extension required for development (like a linter) is only installed locally, VS Code will display a warning icon (⚠) and an Install in WSL button to help you install it in the remote environment.

  12. Control access to .wslconfig settings

    main

    Settings in the Intune Settings Catalog that end with *UserSettingConfigurable control access to advanced WSL settings defined in the .wslconfig file.

    When these settings are set to Disabled, users are restricted to the default values for those specific parameters and cannot apply custom configurations via .wslconfig (such as wsl2.kernel, wsl2.networkingmode, etc.).