v2 Features
A tour of the app, page by page. Features marked BETA in the UI are new and still settling — they work, but expect rough edges and please report anything odd.
This page describes the Windows build. On a Mac the same screens manage virtual machines instead of WSL distros — the differences are collected on the macOS page.
- Installation
- Managing instances
- Creating an instance
- Service recipes
- Snippets
- Community snippets and sharing
- Distro packages (.wsl)
- Templates (deprecated on Windows)
- Mount Disk
- Settings
- Turnkey images
- Docker images
See also: AI Assistant · AI Workspace · MCP Server · Remote WSL · Free vs Pro
Windows (Windows 10 1903+ or Windows 11, with WSL 2):
| Method | How |
|---|---|
| Microsoft Store (recommended, unlocks Pro) | WSL Manager on the Store |
| winget | winget install Bostrot.WSLManager |
| Scoop | scoop install extras/wsl2-distro-manager |
| Chocolatey (community package by @mikeee) | choco install wsl2-distro-manager |
| Portable / installer | zip, MSIX and .exe on the Releases page |
| Nightly | artifact of the releaser workflow, or this link |
macOS (beta): a .dmg / .zip is attached to each GitHub release and produced as a nightly artifact of the macOS workflow. See macOS → Install for requirements and the first-launch Gatekeeper step.
The Home page lists every WSL distro on your machine with its size on disk, and a Recommendations strip above the list that points out things worth doing (an instance over 10 GB that could be compacted, a service that needs systemd, …). Recommendations can be dismissed.
Each row starts with a ▶ / ⏹ button to start or stop the instance, followed by a terminal button and the action row:
| Action | What it does |
|---|---|
| Open terminal | Starts a shell in the distro (uses your configured terminal, default Windows Terminal) |
| Open with VS Code | Launches VS Code attached to the distro |
| Save as template | Exports the instance as a reusable template (see Templates) |
| Open with File Explorer | Opens the distro's filesystem in Explorer |
| Copy | Duplicates the instance (disk included) under a new name — the source is stopped first |
| Rename | Changes the label shown in the app (the WSL name stays the same) |
| Disk usage | Shows used vs. allocated space, lets you resize (grow) the virtual disk and toggle sparse mode |
| Cleanup | Compacts the virtual disk to reclaim space WSL never gives back on its own. Checks for enough free space first |
| Run a snippet | Executes one of your saved snippets inside the distro |
| Settings | Per-instance settings (below) |
| Delete | Unregisters the distro — irreversible, export or package it first if unsure |
Per-instance settings write the distro's /etc/wsl.conf for you: default user, systemd, start command and start directory, automount root and options, /etc/fstab mounting, interop and PATH appending, hostname and hosts/resolv.conf generation, GPU, Windows time zone, and a download override for the rootfs URL. The same dialog holds Move — on a current WSL it runs wsl --manage --move, a single supported operation where the distro is never unregistered; on older WSL versions it falls back to export → unregister → import — and Sync, which serves the instance to another PC running the app (see Settings → Sync).
Long operations (copy, move, cleanup, package, …) show progress in the status bar and can be stopped.
Add an instance opens the creation page.
Pick a Source Type:
- Download from Repo — pick a distro from the built-in catalogue (Debian, Ubuntu, Alpine, Kali, openSUSE, Fedora, Arch and more — every entry is install-tested). The catalogue is a JSON file you can replace with your own repository under Settings.
- Turnkey Linux (LXC) — see Turnkey images
-
Local RootFS File — import a
.tar/.tar.gz/.tar.xzrootfs you already have - Docker Image — see Docker images
- Import VHDX — attach an existing virtual disk in place, nothing is copied
Optionally set a custom install path, have the app create a default (non-root) user — works on Debian/Ubuntu-based images — and pick a service recipe to install on first run.
One-click, Docker-based installs of common development services into any instance. Choose one on the create page (installs the first time the instance runs) or ask the AI assistant for it. The app installs Docker inside the instance if it is missing, starts the container and reports where the service is reachable plus its dev credentials.
| Recipe | Image | Reachable at | Dev credentials |
|---|---|---|---|
| MinIO (S3) | minio/minio |
console on :9001
|
shown after install |
| PostgreSQL | postgres:16 |
:5432 |
user postgres, password postgres, db postgres
|
| MySQL | mysql:8 |
:3306 |
user root, password root, db app
|
| ClickHouse | clickhouse/clickhouse-server |
HTTP :8123 (+ native port) |
default user, no password |
| Redis | redis:7 |
:6379 |
— |
| RabbitMQ | rabbitmq:3-management |
management UI :15672 (+ AMQP port) |
shown after install |
| Kafka (Redpanda) | redpandadata/redpanda |
:9092 |
— |
These are meant for local development — the credentials are deliberately trivial. The same catalogue is exposed to AI agents as the wsl_list_recipes / wsl_install_service MCP tools, and it is backend-agnostic, so it works in a Linux VM on macOS as well.
Formerly "Quick Actions"
Snippets are small bash scripts you can run inside any instance — handy for setting up a predefined environment or doing repetitive maintenance across several distros at once. They run as root inside the instance you pick.
Create one with Add a snippet. The snippet editor has the same fields the community repository expects (name, description, version, author, licence, project URL, the distros it works on, and the script), so a snippet can later be shared without rewriting anything. A snippet named "Test" might look like:
apt-get update
apt-get install python
echo "test" > /tmp/testfileRun it from any distro's action row → Run a snippet → Test. The AI assistant and MCP clients can list, read, create and delete snippets too.
Here's a short video of the workflow:
quick_actions_demo.mp4
Add community snippets opens the Community snippets screen: ready-made scripts from bostrot/wsl-scripts, with filters. Pick the ones you want and they are added to your snippets.
Share with community on one of your own snippets opens a pull request on that repository adding it as info.yml + script.noshell. You sign in to GitHub once through GitHub's device flow (a code you confirm in the browser); the app never sees your password and ships no secret.
If sharing answers "Device Flow must be explicitly enabled for this App", the GitHub OAuth app hasn't been switched on yet on GitHub's side — it is a configuration step on the project, not something you can fix locally. Please report it.
Distro packages turn a configured instance into a portable .wsl file — Microsoft's official custom-distribution format: a root filesystem archive plus an /etc/wsl-distribution.conf that tells WSL how to set the distro up. A package installs on any machine with a current WSL (wsl --install --from-file, or just double-click it), not only through this app.
- Package as .wsl — exports the selected distro (it is stopped first; the file is about as large as the distro). Set the default name, default user ID, first-run (OOBE) command and an optional shortcut icon. gzip is the recommended format.
-
Readiness — before packaging, the distro is checked against Microsoft's recommendations: is there a
wsl.confstating whether systemd starts, is the first-run command present and executable, is a stray/etc/resolv.confabout to bake in wrong DNS settings, and so on. -
Install package — installs a
.wslfile, honouring the settings the package carries.
Building and installing packages needs the Microsoft Store build of WSL (update it from Settings → Global configuration if the page says so).
A template is a saved instance image you can stamp new instances from (Save as template in a distro row, then Create from template). On Windows templates are deprecated: Distro packages do the same job in the official format and install anywhere. Existing templates keep working, but expect them to be removed or merged into packages in a later release.
On macOS templates stay first-class: a template there is a saved VM disk image (see macOS).
Attach a physical disk, a VHD image, or unmount something you previously attached.
- Physical Disk — pick a drive detected on your system
-
VHD Image — mount a
.vhd/.vhdxfile - Unmount — detach a previously mounted disk
Optional fields let you pin a partition number, filesystem type (e.g. ext4), and mount options. Bare attaches the disk to WSL without mounting a filesystem, which is what you want if you plan to handle mounting yourself inside Linux. Mounting needs administrator rights — Windows prompts for them.
| Section | Contents |
|---|---|
| General settings | Default distro/data locations, default editor, terminal and VS Code command, custom rootfs repository, Remote WSL over SSH, and app language |
| Docker settings | Docker registry mirror and repository used for Docker images |
| Bring Your Own AI Key (BETA, Pro) | The AI provider for the AI assistant: your own OpenAI-compatible key, or Sign in with Claude |
| MCP Server (WSL API) (BETA, Pro) | Expose WSL to AI agents, connect Claude Desktop, optional Cloudflare tunnel — see MCP Server |
| Sync settings | Copy a whole instance between two PCs running the app on the same network (one serves it, the other downloads it; password protected) |
| Global configuration | Writes .wslconfig: memory, processors, swap, networking mode, firewall, DNS, nested virtualization, VM idle timeout, debug console and more. Values are validated before they are written |
| Experimental settings | WSL's own experimental flags: auto memory reclaim, sparse VHD, DNS tunneling, ignored ports, etc. |
Changing the language requires an app restart. Stop WSL shuts down the whole WSL subsystem; Edit .wslconfig directly opens the raw config in your editor. Changes to .wslconfig apply after the next wsl --shutdown.
Turnkey Linux images can be used to create instances quickly.
turnkey-init — Turnkey instances can be initialised by running turnkey-init in the console. This lets you choose new passwords for the bundled services.
fake_systemd — as systemd isn't officially supported in WSL, fake_systemd (a fork from @kvaps adapted for WSL) makes Turnkey services actually start when you open the instance.
Since v1.7.0
You can use a rootfs from Docker Hub as your distro — Docker itself is not required. Choose Docker Image as the source type, or type the reference directly:
dockerhub:image_to_use:tag_to_use
for example:
dockerhub:ubuntu:latest
Browse available images on Docker Hub. You can point the app at a different registry or a pull-through mirror under Settings → Docker settings.