WSL Manager for VS Code

Manage your Windows Subsystem for Linux distributions directly from the VS Code sidebar.

Note: This is a community-developed extension and is not affiliated with, endorsed by, or supported by Microsoft. "Windows Subsystem for Linux" and "WSL" are trademarks of Microsoft Corporation.

Features

Sidebar View

Click the WSL icon in the Activity Bar to see all installed distributions with their name (★ for default), state (Running / Stopped), and WSL version (1 / 2). The list refreshes automatically at a configurable interval.

Lifecycle Management

WSL Containers (Preview)

If your WSL version includes the WSL container preview feature (wslc.exe), the sidebar shows Containers and Images sections:

If wslc.exe is not detected, a hint entry appears instead — WSL containers currently require the WSL pre-release channel (wsl --update --pre-release). The sections can be hidden with the wslManager.containers.enabled setting.

What "Connect VS Code" changes on your machine

Attaching VS Code to a container goes through the Dev Containers extension, so this command touches two things outside this extension. Both are disclosed here because they affect other tools:

Install with Custom Instance Name

Install new distributions from the online catalog (wsl --list --online) and assign a custom instance name. The extension automatically detects your WSL version and selects the best installation strategy:

When cloud-init or a cached image is used, the flow adapts accordingly — see sections below.

Distribution Image Cache

Caches distribution images locally after the first download to speed up repeated installs and save bandwidth.

Cache location: %LOCALAPPDATA%\WSLManager\cache\

cloud-init Provisioning

Supported distributions can be automatically provisioned during install using a cloud-init user-data config file (YAML). When provided, user creation, package installation, and custom setup are all handled by cloud-init — no manual OOBE or password input needed.

How it works: The extension places the YAML file at %USERPROFILE%\.cloud-init\<instanceName>.user-data before the first boot. cloud-init reads it automatically on startup.

Config Management: The sidebar includes a "Cloud-Init Configs" section where you can manage your configs:

Two built-in sample configs are included: "Default" (common development tools) and "Docker" (Default + Docker CE). Configs are stored as YAML files in %APPDATA%\Code\User\globalStorage\jkudo.wsl-manager\cloud-init\.

When installing from cache with cloud-init, the extension automatically resets cloud-init state and runs all stages in the background — no manual terminal interaction needed.

Supported distributions:

• AlmaLinux 8 / 9 / 10
• Fedora Linux
• Ubuntu 20.04 / 22.04 / 24.04 LTS
• Oracle Linux 8 / 9
• openSUSE Leap 15.6 / 16.0, Tumbleweed
• SUSE Linux Enterprise 15 / 16
• eLxr

Example cloud-init config:

#cloud-config

locale: ja_JP.UTF-8
timezone: Asia/Tokyo

users:
  - name: dev
    groups: [adm, sudo]
    sudo: ALL=(ALL) NOPASSWD:ALL
    shell: /bin/bash

write_files:
  - path: /etc/wsl.conf
    append: true
    content: |
      [user]
      default=dev

packages:
  - git
  - curl
  - build-essential

runcmd:
  - sudo -u dev git config --global init.defaultBranch main

cgroup v1 Management

Automatically adds kernelCommandLine = cgroup_no_v1=all to .wslconfig on every install. This can be changed in WSL Settings under the Kernel section.

WSL Settings Editor

A VS Code-style settings GUI for .wslconfig. Open from the … menu → WSL Settings.

Grouping

Organize distributions into custom groups displayed as folders in the sidebar. Drag and drop to move distributions between groups or reorder them.

A default group ("General") always exists and cannot be deleted. New distributions are assigned to a group during the install wizard. If only one group exists, assignment is automatic.

Distribution Management

Backup, Restore & Clone

Development Tools

If you disable [interop] or [automount] in wsl.conf: the WSL remote extension normally starts its server through a script that depends on those features, so Connect to WSL can stop working after the distribution restarts. The fix is the WSL extension's scriptless startup mode — add "remote.WSL.experimental.scriptLessStartup": true to your VS Code settings (Settings → search "scriptless"). "Edit wsl.conf" itself is not affected: it writes over stdin precisely so you can always edit the settings back.

Usage

From the Sidebar

1. Click the WSL icon in the Activity Bar
2. Right-click a distribution to open the context menu
3. Hover over a distribution to reveal inline action buttons (terminal, start/stop)

From the Command Palette

Ctrl+Shift+P → type WSL Manager: to see all available commands.

Install Wizard Flow

Step 1: Select distribution (Cached / Online)
Step 2: Enter custom instance name
Step 3: Select group (if multiple groups exist)
Step 4: Select cloud-init config (saved configs / file / skip)
Step 5: Cache/fresh choice or install directory (if applicable)
Step 6: Username + password (only when no cloud-init and no OOBE)
  ↓
Install → Configure .wslconfig → User setup or cloud-init → Ready

Settings

Requirements

• Windows 10 (21H2+) or Windows 11
• WSL installed and enabled
• VS Code 1.85.0 or later

The container features are optional and detected at runtime — without them the extension works exactly as before:

License

MIT