# yuk7/wsldl: A Portable WSL Distribution Launcher

> yuk7/wsldl registers Linux root filesystems or ext4 VHDX images as WSL distributions and provides an instance-specific launcher for configuration, backups, imports, and terminal selection. It suits Windows users who want more control over distribution files than the standard installation path provides.

**yuk7/wsldl** — Advanced WSL launcher / installer. (Win10 FCU x64/arm64 or later.)

- Repository: https://github.com/yuk7/wsldl
- Website: https://git.io/wsldl
- Stars: 1,948 · Forks: 136
- Language: Go
- License: MIT
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/yuk7-wsldl

## What yuk7/wsldl Adds to Windows Subsystem for Linux

yuk7/wsldl addresses a specific WSL packaging problem: installing or launching a Linux distribution from a local root filesystem rather than relying exclusively on a prebuilt distribution package. The README lists support for tar-based root filesystems, ext4 VHDX images, and instances that are already registered with WSL. This makes the project relevant to Windows users who maintain custom Linux images, distribute a particular environment, or want the executable filename to determine the registered instance name.

The intended platform is Windows 10 Fall Creators Update 1709 or later on x64 or ARM64, with the Windows Subsystem for Linux feature enabled. wsldl is not itself a Linux distribution and does not replace the Windows-side WSL feature. It acts as the launcher and installer between a filesystem image and the WSL instance registry exposed through commands such as `wslconfig /l`.

Its clearest distinction is the filename convention. If `wsldl.exe` is renamed to `Arch.exe`, the README says it will register or launch an instance named `Arch`. An existing instance such as `Ubuntu-20.04` can likewise use a launcher named `Ubuntu-20.04.exe`. That makes each executable distribution-specific without requiring a separate global wrapper name for every instance. The trade-off is that renaming is part of operation rather than a cosmetic step. A mismatched filename can point the launcher at the wrong registered name.

## How Rootfs and VHDX Files Become WSL Instances

For a tarball installation, wsldl expects `install.tar` or `install.tar.gz` in the same directory as the executable. The README also warns that the Linux filesystem must be at the root of the tarball, so some third-party rootfs archives may have to be repacked before installation. Running the renamed executable starts the installation process, which the documentation says may take several minutes.

The VHDX route is narrower. wsldl accepts `install.ext4.vhdx` or `install.ext4.vhdx.gz`, but the README labels this method WSL2 only. After installation, the executable opens a shell with default settings while inheriting the current Windows directory, except that `%%USERPROFILE%%` becomes `$HOME`. It can also run a complete command in the instance, or translate a Windows path before running it. These launch modes come from the executable's documented interface.

Per-instance configuration is handled through a `config` command. The documented settings include `--default-user`, `--default-uid`, `--append-path`, `--mount-drive`, `--wsl-version`, and `--default-term`. The terminal choices documented for `--default-term` are `default`, `wt`, and `flute`. The README does not describe the internal Go packages, registry schema, or exact startup sequence beyond these user-facing operations, so claims about the implementation beyond that interface would not be supportable.

## Installing yuk7/wsldl and Registering a Custom Distribution

The README directs users to the latest release for `wsldl.exe` and `wsldl_arm64.exe`. Before running either file, Windows must meet the stated requirements and the WSL feature must already be enabled. For a tarball distribution, the installation directory needs two files: the architecture-appropriate executable and an archive named exactly `install.tar` or `install.tar.gz`. The executable itself must also have the name that should be registered as the instance.

After placing the files together, run the renamed executable to begin installation. The README does not print a literal launch command for this initial step because it instructs the reader to run the renamed executable itself. Installation is expected to take a few minutes. Once the distribution is registered, its own help command exposes the available operations:

```cmd
>{InstanceName}.exe help
```

That command prints the documented launcher interface, including `run`, `runp`, `config`, `get`, `backup`, `install`, `clean`, and `help`. A user who needs a prebuilt package rather than a custom image is directed to the documentation's distribution list instead. The README does not document package selection details, so selecting and installing from that catalog cannot be reduced to a verified command here.

## Launching Commands and Converting Windows Paths

The basic launch operation starts a shell for the named instance. It inherits the directory from which the launcher is invoked, except for the documented `%%USERPROFILE%%` translation. Commands can also be passed directly to the distribution. This is useful for scripts or for checking the running kernel without manually entering an interactive shell first:

```cmd
>{InstanceName}.exe run uname -r
```

The README shows `4.4.0-43-Microsoft` as the example output, although that is an illustrative result and not a guaranteed kernel version for every installation.

`runp` performs path conversion before executing the command. For example, the documented Windows path is presented to Linux as a path under `/mnt/c`:

```cmd
>{InstanceName}.exe runp echo C:\Windows\System32\cmd.exe
/mnt/c/Windows/System32/cmd.exe
```

This distinction matters when the command contains a Windows file path. `run` inherits the current directory and accepts a command line, while `runp` is the documented choice when conversion is part of the request. The README does not describe quoting rules for command lines containing multiple options or special characters, so complex automation would need verification against the executable's help and local command behavior.

## Configuring Users, WSL Versions, Paths, and Terminals

A launcher can act as the administrative entry point for one registered WSL instance. The default user can be set by name or numeric UID, while path import, drive mounting, WSL version, and terminal selection are controlled with Boolean or enumerated values. For example, the README documents selecting Windows Terminal as the default:

```cmd
>{InstanceName}.exe config --default-term wt
```

Changing the default user uses the documented `config` syntax and takes effect when the instance is launched:

```cmd
>{InstanceName}.exe config --default-user user
```

The `get` command exposes `--default-uid`, `--append-path`, `--mount-drive`, `--wsl-version`, `--default-term`, `--wt-profile-name`, and `--lxguid`. This creates a discoverable configuration surface without requiring the reader to infer the accepted option names from Go source. The source directory exists in the repository, but the README does not map each setting to an internal configuration file or explain failure handling.

WSL version selection is constrained to `1` or `2` by the interface. Drive mounting can be switched independently, as can appending the Windows PATH to the Linux PATH. Those controls can produce behavior differences across instances, so administrators should avoid copying a launcher configuration from one distribution to another without checking whether its filesystem and intended workflow support the same settings.

## Backup, Restore, and Removal Boundaries

The launcher documents backups in tar and ext4 VHDX formats, with optional gzip compression. A tar backup is available for WSL1 or WSL2, while ext4 VHDX output is WSL2 only. The following command writes a compressed tar backup:

```cmd
>{InstanceName}.exe backup backup.tar.gz
```

The corresponding WSL2 compressed VHDX command is:

```cmd
>{InstanceName}.exe backup backup.ext4.vhdx.gz
```

A `.reg` output is also documented for settings. Restore uses the `install` command. These examples match the supported file naming rules:

```cmd
>{InstanceName}.exe install backup.tar.gz
>{InstanceName}.exe install backup.ext4.vhdx.gz
```

Removal is separate from backup. The `clean` command uninstalls the instance:

```cmd
>{InstanceName}.exe clean
```

The README does not state whether `clean` asks for confirmation, whether it removes all files associated with the installation, or how to undo registration. It also does not document rollback for an interrupted installation. The safest supported distinction is simple: `backup` creates an archive or image, `install` imports one, and `clean` uninstalls the instance. Any recovery behavior beyond those commands would need confirmation in the project's detailed documentation.

## Maintenance, License, and Operational Trade-offs

The repository is not archived, and its last push was on 2026-10-13. Recent releases include `26032000` from 2026-03-20, `25051300` from 2025-05-12, and `25031900` from 2025-03-19. These dates indicate recent repository activity and versioned releases, but the README does not provide a compatibility matrix covering every release, Windows build, architecture, or WSL implementation.

wsldl is written primarily in Go and is distributed under the MIT License. The README identifies copyright from 2017 to 2025. That license permits broad use, modification, and redistribution subject to its terms, but this review does not provide legal advice. The practical upgrade cost is not limited to replacing an executable: an existing launcher can depend on a matching registered instance name, local rootfs or VHDX files, and configuration semantics. Upgraders should preserve backups and compare the new executable's `help` output before migrating settings.

The principal limitation is platform scope. wsldl requires Windows 10 1709 or later and the WSL feature. Its custom VHDX workflow is WSL2 only, and tar archives must place the filesystem at the archive root. It is the wrong choice for Linux or macOS hosts, users seeking a general-purpose terminal emulator, or anyone who wants Windows Update or Microsoft Store to manage the distribution lifecycle. A real alternative is using WSL's built-in distribution installation and management path, which avoids the filename-based wsldl launcher and custom image arrangement but provides fewer instance-specific controls in the interface documented here.

## Conclusion

Adopt yuk7/wsldl if you need a portable, filename-based WSL distribution installer or an instance-specific launcher with configurable users, WSL versions, drive mounting, terminal behavior, and backups. Do not adopt it if you only need a standard distribution managed entirely through Microsoft's built-in tools or if your Windows system lacks the required WSL feature. Verify first that Windows 10 1709 or later is available, choose the correct x86_64 or ARM64 executable, and confirm that the root filesystem is located at the root of the archive or use a WSL2-compatible ext4 VHDX image.

## FAQ

### What operating system and hardware does yuk7/wsldl require?

The README requires Windows 10 Fall Creators Update 1709 or later on x64 or ARM64, with the Windows Subsystem for Linux feature enabled. The project provides x86_64 and ARM64 executable builds.

### How do I install a Linux root filesystem with yuk7/wsldl?

Place `install.tar` or `install.tar.gz` in the same directory as the correctly named wsldl executable, then run that executable. The filesystem must be at the root of the tarball, and some rootfs archives may need repacking.

### Can yuk7/wsldl use an ext4 VHDX image?

Yes, but the README limits this installation method to WSL2. It expects `install.ext4.vhdx` or `install.ext4.vhdx.gz` beside the executable.

### How do I launch and configure a yuk7/wsldl instance?

Rename the executable to the registered instance name and run it without arguments to open a shell. The `config` command changes settings such as the default user, WSL version, drive mounting, appended PATH, and terminal type.

### How do I back up or remove a yuk7/wsldl distribution?

Use `backup` with a supported `.tar`, `.tar.gz`, `.ext4.vhdx`, `.ext4.vhdx.gz`, or `.reg` filename. Use `clean` to uninstall the instance, although the README does not describe its confirmation or file-removal behavior.

## Sources

- [License: MIT](https://github.com/yuk7/wsldl/blob/main/LICENSE)
- [Project website](https://git.io/wsldl)
- [README](https://github.com/yuk7/wsldl/blob/main/README.md)
- [Releases](https://github.com/yuk7/wsldl/releases)
- [yuk7/wsldl on GitHub](https://github.com/yuk7/wsldl)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/yuk7-wsldl