Skip to main content

How to Install WSL from a Batch Script

The Windows Subsystem for Linux (WSL) is a powerful tool for developers, but its manual installation involves several steps: enabling features, downloading kernels, and choosing a distribution. To streamline this process for teams, students, or automated lab setups, you can use a Batch script to trigger the entire installation with a single command. In modern versions of Windows 10 and 11, Microsoft has simplified this drastically with the wsl --install command.

This guide will show you how to build a script that handles prerequisites, installs the subsystem, and prepares a specific Linux distribution silently.

Prerequisites for Automation​

Before running a script to install WSL, ensure the following:

  • Windows Version: Windows 10 version 2004 or higher, or Windows 11.
  • BIOS/UEFI: Virtualization Technology (VT-x or AMD-V) must be enabled in the firmware.
  • Internet Access: The script needs to download the Linux kernel and the chosen distribution (e.g., Ubuntu).
Administrative Privileges Required

Modifying the Windows boot configuration and enabling system-level features like the "Virtual Machine Platform" requires elevated permissions. You MUST run your Batch script as an Administrator.

Method 1: The Modern One-Command Method (Best Practice)​

On up-to-date systems, a single command now handles enabling the features and downloading the default distribution (Ubuntu).

@echo off
echo ============================================================
echo   WSL Automated Installer
echo ============================================================

:: 1. Check for Administrative Privileges
net session >nul 2>&1
if %errorlevel% neq 0 (
    echo [ERROR] Please run this script as Administrator.
    pause
    exit /b 1
)

:: 2. Check if WSL is already installed
where wsl.exe >nul 2>&1
if %errorlevel% equ 0 (
    reg query "HKCU\Software\Microsoft\Windows\CurrentVersion\Lxss" >nul 2>&1
    if %errorlevel% equ 0 (
        echo [INFO] WSL is already installed with at least one distribution.
        echo [INFO] Run 'wsl --update' to ensure the kernel is current.
        pause
        exit /b 0
    )
)

:: 3. Run the Simplified Install
echo [PROCESS] Enabling features and downloading default kernel...
wsl --install --no-launch

if %errorlevel% equ 0 (
    echo ============================================================
    echo   WSL Installation Initiated!
    echo   [IMPORTANT] You MUST restart your computer to finish.
    echo ============================================================
) else (
    echo [ERROR] Installation failed. Error code: %errorlevel%
    echo [HELP] Ensure you have internet access and are running
    echo [HELP] Windows 10 version 2004 or later.
)
pause

Method 2: Installing a Specific Distribution Silently​

If your project requires a specific version of Linux (like Debian or a specific Ubuntu build), you can specify it in your script.

@echo off

:: Check for Administrative Privileges
net session >nul 2>&1
if %errorlevel% neq 0 (
    echo [ERROR] Please run this script as Administrator.
    pause
    exit /b 1
)

echo [PROCESS] Installing WSL with Debian distribution...

:: List available distros: wsl --list --online
wsl --install -d Debian --no-launch

if %errorlevel% equ 0 (
    echo [SUCCESS] Debian installation queued.
    echo [IMPORTANT] You MUST restart your computer to finish.
) else (
    echo [ERROR] Installation failed. Error code: %errorlevel%
)
pause

Method 3: The Manual/Legacy Way (Manual Component Control)​

If you are on an older build or need to handle the components individually for better control, use the DISM tool.

@echo off

:: Check for Administrative Privileges
net session >nul 2>&1
if %errorlevel% neq 0 (
    echo [ERROR] Please run this script as Administrator.
    pause
    exit /b 1
)

echo [PROCESS] Manually enabling WSL components...

:: 1. Enable WSL Subsystem
echo [STEP 1/2] Enabling Windows Subsystem for Linux...
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
if %errorlevel% neq 0 (
    echo [ERROR] Failed to enable WSL feature. Error code: %errorlevel%
    pause
    exit /b 1
)

:: 2. Enable Virtual Machine Platform (Required for WSL2)
echo [STEP 2/2] Enabling Virtual Machine Platform...
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
if %errorlevel% neq 0 (
    echo [ERROR] Failed to enable Virtual Machine Platform. Error code: %errorlevel%
    pause
    exit /b 1
)

echo [SUCCESS] Features enabled.
echo [NEXT STEPS] After reboot, run 'wsl --update' and 'wsl --install -d Ubuntu'.
pause

Common Pitfalls and How to Avoid Them​

Multiple Reboots​

Installation is not finished until the machine reboots. If you attempt to use WSL commands immediately after the script finishes, they will fail.

Wrong Way:

wsl --install
wsl -d Ubuntu ls /
:: This will error out because the subsystem hasn't initialized the kernel yet.

Correct Way: Always end your script with a clear instruction to reboot, or use the shutdown /r /t 0 command to automate the restart.

Virtualization Errors (Error 0x80370102)​

This is the most common error. It means the Windows feature is on, but the BIOS/UEFI "Virtualization" setting is off.

SEO and UX Tip

Advise your users that if they see a 0x80370102 error after rebooting, they must enter their BIOS (press F2 or Del) and enable Intel VT-x or AMD-V. No software script can fix a BIOS-level hardware block.

Best Practices for Enterprise Rollouts​

  1. Skip First Launch: Use the --no-launch flag. This prevents the Linux terminal from opening and asking for a username/password while your Batch script is still running.
  2. Verify Pre-install: Always check if WSL is already installed before trying to install it again to avoid "Already Exists" warnings.
  3. Kernel Updates: After the initial install, it is good practice to run wsl --update to ensure the Linux kernel is on the latest security version.
Network Proxies

If you are behind a corporate proxy, wsl --install may fail to download the distribution from the Microsoft Store. You may need to download the .appx file manually and use wsl --import.

Conclusion​

Installing WSL via Batch script is the professional way to deploy Linux capabilities across one or one hundred machines. By leveraging the simplified --install command or the precision of DISM, you can build a reliable and repeatable environment for your development team. This automated approach ensures that every user starts with the same foundational tools, reducing configuration drift and allowing everyone to focus on writing code rather than troubleshooting their operating system features.

Table of Contents