microsoft / microsoft/WSL

Enable easily using existing distributions from existing official upstream sources

Open
#13,099 6 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

feature
Dominant language
C++
Stars
33.7k
Forks
1.8k
Avg merge
3d 17h
Merged PRs (30d)
116

Description

**Is your feature request related to a problem? Please describe.**

I want to use the most recent Alpine as a WSL2 distribution. Currently there isn't one.
I have to perform the following:

1. Go the Alpine Linux website, and locate there the latest `.tar.gz` of Alpine.
2. Download and extract it.
3. Add all the files WSL likes (`/etc/wsl-distribution.conf`, etc.)
4. Assemble back a `.tar.gz` file.
5. Upload it somewhere.
6. Add the file from the previous item to my custom distributions JSON.

There's a fellow who does more or less that, but they're still on 3.21 when 3.22 is already out for two weeks. They distributes their Alpine WSL in the legacy format, and they have to manually launch the build process (which they probably haven't done yet, which is why there's no new version).

But unfortunately my troubles aren't over yet.

Now I want to run Gentoo as a WSL2 distribution. This is only a bit easier.
The Gentoo project provides a `.wsl` file, but I still have to go to their website and there locate the correct file and add it to my custom distributions JSON.

And I have to do that every time.

**Describe the solution you'd like**

I'd like a built-in way to provide WSL a dynamic list of distributions, and I'd like a "distribution" to mean noy only a root filesystem in a `.tar`, but also some actions to perform, such as injecting file into the VHD into which the `.tar` is extracted.

I'll first explain the second component. Consider something like:

```json
{
"ModernerDistributions": {
"Alpine": [
{
"Name": "Alpine-3.22.0",
"Default": true,
"FriendlyName": "Alpine Linux 3.22.0 (latest)",
"Amd64Url": {
"Url": "https://dl-cdn.alpinelinux.org/alpine/v3.22/releases/x86_64/alpine-minirootfs-3.22.0-x86_64.tar.gz",
"Sha256": "",
"Files": {
"/etc/wsl-distribution.conf": {
"Source": "url",
"Url": "",
"Sha256": ""
},
"/etc/oobe.sh": {
"Source": "inline",
"Contents": "#!/bin/bash [...]"
}
}
},
"Arm64Url": {
[...]
}
},
{
"Name": "Alpine-3.21,3",
"Default": false,
"FriendlyName": "Alpine Linux 3.21.3"
[...]
}
}
}
```

Note that it uses the upstream Alpine `.tar.gz`, without requiring anyone to manufacture a new "WSL-ized" `.tar.gz` and WSL injects the required files into the VHD after extracting the contents of the upstream rootfs.

But this still requires somebody to maintain the list. That's where the first part comes into play. Instead of WSL consuming static data (the JSON file), it should use some sort of dynamic data source, e.g. a JS file that generates JSON data (similar to WPAD PAC files). Such a script could enumerate the files on the upstream servers (or read a manifest if they provide one), and generate a current, live list.

**Describe alternatives you've considered**

1. We can run a small local server that does that.
That's pretty annoying and causes friction. If WSL itself did this, usage would be much more streamlined.
What's even more problematic is that it's local for every user. It doesn't really allow us to publish the dynamic distributions lists.

2. We can run a small online server that does that.
That has costs, both in $$ and in time and effort of managing a server etc.

**Additional context**

See also #13098 for another improvement request regarding the distribution lists.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by locating the existing custom distribution JSON handling and the path that extracts root filesystems into VHDs. The issue proposes dynamic upstream distribution data plus file injection; done would mean WSL can consume current upstream archives and apply the required files without manually repackaging or maintaining each entry.

Written by the indexing model from the issue text.

Assessment

Tech stack
cpp
Domain
operating-systems
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.