WSL Commander

A modern Windows desktop application for managing your Windows Subsystem for Linux (WSL) distributions and WSL Containers — built with Python and PyQt6 Fluent Widgets.

---

Features

• View all installed WSL distributions with live status and version info
• Launch a terminal for any distribution with a single click
• Set a distribution as the system default
• Stop a running distribution
• Remove a distribution
• Export a distribution to a .tar archive for backup or transfer
• Install new distributions from the official online catalogue
• Import a distribution from a .tar archive with a custom name and install location
• Share USB devices with WSL, including bind, unbind, attach, detach, and auto-attach workflows
• Browse USB devices in a sortable table with color-coded device states
• Manage WSL containers alongside distributions on a unified page, with an All / Distros / Containers filter, expandable container details, logs, and start/stop/remove actions (requires WSL 2.9.3+)
• Use a modern Fluent Design UI with automatic light/dark theme support

What's New in v1.1.0

• Added an inline Install button directly on the selected distribution card in the install catalogue.
• Improved USB device visibility with color-coded state labels.
• Added a sortable USB device table for easier browsing.
• Added USB Auto-Attach support, including optional handling for unplugged devices.
• Added automatic UAC elevation for USB bind and unbind operations when administrator rights are required.
• Included minor code cleanup and maintenance updates.

For a release-by-release history, see CHANGELOG.md. The release notes for v1.1.0 are available in docs/release-notes-v1.1.0.md.

---

Screenshots

Installed Distributions

Install / Import a Distribution

USB Device Management

---

Requirements

• Windows 10 or Windows 11 with WSL2 enabled
• usbipd-win (optional — required for USB sharing functionality)

Enable WSL2 (if not already set up)

Open an elevated PowerShell and run:

wsl --install

Restart your machine before launching WSL Commander.

Enable WSL container support (optional)

Container management uses Microsoft's wslc.exe container CLI, which ships with WSL 2.9.3 or higher. This is currently available as a pre-release. To enable it, open PowerShell and run:

wsl --update --pre-release

Confirm your version with wsl --version. Without a compatible WSL version, WSL Commander still runs and manages distributions normally — the container filter is simply hidden.

Install usbipd-win (for USB sharing)

USB device sharing requires usbipd-win. Install it via winget:

winget install usbipd

Or download the installer from the usbipd-win releases page.

Note: Without usbipd-win, the USB page will still open but no devices will be listed and attach/detach actions will not be available.

Note: Binding and unbinding USB devices may trigger a Windows UAC prompt if WSL Commander is not already running with administrator privileges.

---

Running the Application

Option 1 — Pre-built Executable (no Python required)

1. Download the latest release from the GitHub Releases page.
2. Extract the zip archive.
3. Run WSLCommander.exe from the extracted folder.

Note: The executable is self-contained. No Python or additional dependencies need to be installed.

Option 2 — Run from Source

Prerequisites: Python 3.10 or higher.

1. Clone the repository

git clone https://github.com/hpconcept/WSLCommander.git
cd WSLCommander

2. Create a virtual environment (recommended)

python -m venv .venv
.venv\Scripts\activate

3. Install dependencies

pip install -r requirements.txt

4. Run

python main.py

---

Building the Executable

The repository includes a PyInstaller spec file for building the standalone executable yourself.

1. Install dev dependencies

pip install -r requirements-dev.txt

2. Build

pyinstaller WSLCommander.spec --noconfirm

The output will be placed in dist\WSLCommander\WSLCommander.exe.

---

Project Structure

WSLCommander/
├── app/
│   ├── main_window.py        # Main application window
│   ├── models/               # Data models (Distro, Container, UsbDevice)
│   ├── pages/                # UI pages (Distributions, Install, USB)
│   ├── utils/                # Helpers (logo resolution, elevation, wslc locator)
│   └── workers/              # Background QThread workers (WSL, containers, USB)
├── assets/
│   ├── distros/              # Distribution logo images
│   └── icon/                 # Application icon
├── docs/
│   └── screenshots/          # Application screenshots
├── main.py                   # Entry point
├── requirements.txt          # Runtime dependencies
├── requirements-dev.txt      # Dev/build dependencies (includes PyInstaller)
├── WSLCommander.spec         # PyInstaller build spec
├── CHANGELOG.md              # Version history and release notes
├── LICENSE                   # MIT License
└── README.md

---

Dependencies

Runtime

Package	License	Purpose
PyQt6>=6.6.0	GPLv3 / Commercial	Qt6 Python bindings
PyQt6-Fluent-Widgets[full]>=1.6.0	GPLv3 (free tier)	Fluent Design UI component library

Dev / Build

Package	License	Purpose
PyInstaller	GPL + exception	Packaging into a standalone executable

---

License

The source code of WSL Commander is licensed under the MIT License — see the LICENSE file for details.

The pre-built binary bundles PyQt6 and PyQt6-Fluent-Widgets, both of which are licensed under GPLv3. As a result, redistribution of the compiled binary is subject to the terms of the GNU General Public License v3.

If you require a license that is compatible with proprietary use, a commercial license for PyQt6 is available from Riverbank Computing and a commercial license for PyQt-Fluent-Widgets is available at qfluentwidgets.com.