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.

Only images that ship cloud-init can use this. WSL merely puts the file where cloud-init looks; if the image does not include cloud-init (openSUSE Leap 16.0, for example), the file is never read. The extension checks for cloud-init right after installing and, when it is missing, falls back to the distribution's own initial setup: it opens a terminal so the first-run wizard ([oobe] command in the image's wsl-distribution.conf) can create the user the way the distribution intends. It does not create users by itself in that case. The same fallback applies when cloud-init ran but created no user.

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

Connecting when interop is disabled (Remote-SSH)

Setting [interop] enabled=false in wsl.conf keeps tools inside the distribution (Claude Code, npm, git, …) from ever seeing Windows executables or /mnt/c. It also breaks the WSL remote extension: its server startup script needs Windows executables and /mnt/c, so the window fails with WebSocket close with status code 1006.

WSL Manager handles this by connecting through the Remote - SSH extension instead:

• The tree shows an Interop: disabled detail row for such distributions, Connect to WSL is greyed out in the context menu, and Connect to WSL via SSH is the one to use (from the Command Palette, Connect to WSL switches automatically).
• First use asks for confirmation, then prepares the distribution: installs openssh-server and, if the image lacks them, tar/gzip/curl (the VS Code Server cannot be unpacked without them); configures sshd on a port of its own with key authentication only; authorizes your ~/.ssh/id_ed25519.pub (generated if missing) for the default user.
• On the Windows side it writes a Host wsl-<distro> entry into a marked block of ~/.ssh/config, registers the host in remote.SSH.remotePlatform, checks the connection with ssh, and opens the window.
• WSL stops a distribution once its last session ends, which would take sshd down with it, so the extension keeps a hidden background session open while the distribution is in use. Stop and Shutdown All end it.

Each distribution gets its own port (allocated from wslManager.ssh.portRangeStart, default 2222, and read back from the distribution's sshd configuration), so this works under both NAT and mirrored networking with nothing to keep in sync on the Windows side. Sessions opened through the extension's ssh entry also get OPENSSL_CONF=/dev/null, which works around a VS Code CLI hang on distributions whose OpenSSL config includes crypto-policies (openSUSE, Fedora family); nothing else is affected.

To keep using the WSL remote extension instead, turn off wslManager.ssh.useWhenInteropDisabled and enable that extension's scriptless startup ("remote.WSL.experimental.scriptLessStartup": true). Edit wsl.conf works either way, so you can always change the setting back.

Supported distributions

Every distribution offered by wsl --list --online has been verified with both connection modes; the full table is in docs/distro-verification.md. Two things to know:

Legacy, appx-packaged distributions (Oracle Linux, SUSE Linux Enterprise 15 SP6) are installed through their launcher and then renamed with the export/import path; only Ubuntu images ship cloud-init, every other image sets up its first user through its own first-run wizard.

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 → cloud-init, or the distribution's own first-run setup in a terminal → 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