Complete Guide to Configuring WSL Terminal in Windows Terminal

Keywords: Windows Terminal | WSL Configuration | Command Line Parameters | Terminal Customization | Linux Integration

Abstract: This article provides a comprehensive guide to configuring WSL terminal in Windows 10 using Windows Terminal. Covering WSL installation, permission configuration, and detailed Windows Terminal settings including command-line parameters, color schemes, and icon customization. Step-by-step instructions help users resolve WSL terminal launch issues with practical configuration examples and troubleshooting methods.

WSL Installation and Enablement

To successfully launch WSL terminal in Windows Terminal, first ensure Windows Subsystem for Linux is properly installed and enabled. Search and install Ubuntu or other Linux distributions from Microsoft Store, which are core components of WSL.

After installation, run PowerShell as administrator and execute the following command to enable WSL feature:

Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux

After command execution, system restart is required to apply changes. After reboot, enter ubuntu in command prompt to initially launch Ubuntu, where the system will guide through username and password setup process.

Windows Terminal Configuration

Windows Terminal configuration file profile.json is located in user's application data directory. Modify this file to add WSL terminal configuration. Below is a complete WSL configuration example:

{
    "guid": "{78e390db-1bff-4533-9d7c-20f53d8bafa1}",
    "name": "WSL",
    "colorscheme": "Campbell",
    "historySize": 9001,
    "snapOnInput": true,
    "cursorColor": "#FFFFFF",
    "cursorShape": "bar",
    "commandline": "wsl ~",
    "fontFace": "Consolas",
    "fontSize": 12,
    "acrylicOpacity": 0.75,
    "useAcrylic": true,
    "closeOnExit": false,
    "padding": "0, 0, 0, 0"
}

Key configuration parameters explanation:

guid: Unique identifier for each profile, must differ from other configurations
commandline: Set to wsl ~ to directly launch default WSL distribution
wsl ~ -d Ubuntu-18.04: Specify launching particular distribution
acrylicOpacity: Controls terminal background transparency
startingDirectory: Sets startup directory, defaults to user home directory

Command-Line Parameters Detailed

WSL provides rich command-line options to enhance terminal functionality:

wsl.exe -l -v

This command lists all installed WSL distributions and their status. wsl --status displays default distribution information, wsl --set-default <distribution> can change default distribution.

Advanced launch options include:

wsl ~ -u root

Launch WSL as root user, suitable for system administration tasks. wsl ~ -e bash --noprofile --norc skips startup file execution, used for environment debugging.

Color Scheme Customization

Windows Terminal supports custom color schemes. Define color themes in schemes section of profile.json:

"schemes": [
    {
        "name": "Campbell",
        "foreground": "#A7B191",
        "background": "#0C0C0C",
        "colors": [
            "#0C0C0C", "#C50F1F", "#13A10E", "#C19C00",
            "#0037DA", "#881798", "#3A96DD", "#CCCCCC",
            "#767676", "#E74856", "#16C60C", "#F9F1A5",
            "#3B78FF", "#B4009E", "#61D6D6", "#F2F2F2"
        ]
    }
]

Icon Customization

Adding custom icons for different terminal types enhances user experience. Icon files should be placed in:

%LOCALAPPDATA%\packages\Microsoft.WindowsTerminal_8wekyb3d8bbwe\RoamingState

Use ms-appdata:// protocol in configuration file to reference icons:

"icon": "ms-appdata:///local/ubuntu.png"

For Linux distributions, Tux penguin icon is recommended, with corresponding GUID:

{9acb9455-ca41-5af7-950f-6bca1bc9722f}

Common Issue Resolution

If terminal launches CMD instead of WSL, check if commandline parameter is correctly set to wsl related commands. Ensure GUID uniqueness to avoid conflicts with other configurations.

External shell launch issues typically stem from incorrect command-line parameter configuration. Use wsl.exe -d <distribution_name> to precisely specify which distribution to launch.

Permission issues can be resolved by running Windows Terminal as administrator or verifying WSL feature is fully enabled.

Copyright Notice: All rights in this article are reserved by the operators of DevGex. Reasonable sharing and citation are welcome; any reproduction, excerpting, or re-publication without prior permission is prohibited.