Packaging a WSL Distro to MSIX
Published May 20 2022 09:21 AM 2,746 Views

In this post I will demonstrate how to export a WSL distro to a .tar file, and how to use the WSL-DistroLauncher to package it to MSIX.


In case you want to know more details about MSIX, or even get some examples about it, please check the post MSIX: Probably you don't know, but you are already using it.


There are scenarios where you want to customize a WSL Distro, like settings, apps users, etc, before making it available for your users.


Regardless of where you installed the distro (Microsoft Store, Vendor website, GitHub, Docker, etc.), the process will be the same. I mean, once you install your favorite distro, you can customize it as per your needs.


For example, let suppose you were working with the openSUSE-Leap-15.3. After installed it, I customized it with the following Apps:


  • Text Editor
  • Scribus
  • Thunar File






But I got the following encoding error for my Apps:




That I fixed using the steps described at Troubleshooting GUI Linux apps on openSUSE on WSLg.


Once everything was working fine and my distro customization is done, now is time to export the distro to .tar.


The export command expects the distro name, that can be easily obtained through the following command:


wsl -l -v




Once we now the distro name, we can export it using:


wsl --export openSUSE-LEap-15.3 c:\msix\bb\install.tar


Observe that I am naming the distro to install.tar, as this name is expected in the WSL-DistroLaucher project to package the distro to MSIX.


The next step is to compress the .tar file to .gz.


& "$env:ProgramFiles\7-Zip\7z.exe" a .\install.tar.gz .\install.tar





WSL Distro-Launcher


Now that we have the tar.gz, it is time to use the WSL Distro Launcher that is available on GitHub and that is the C++ reference implementation for a Windows Subsystem for Linux (WSL) distribution installer/launcher application. Every distro package must include a launcher app, which is responsible for completing installation & registration of your distro with WSL, and for launching new distro instances atop WSL.


This is the WSL-DistroLaucher solution structure:




Adding install.tar.gz to the solution

The first part is to add the install.tar.gz file, created previously, to our solution:





Let's start by the manifest file (MyDistro.appxmanifest). This is the manifest used by MSIX applications, and in our case, we are interested in defining the display name, description, assets (images of the applications available on Start menu) of our distro. In my case, I am naming the MSIX package to WSL-openSuse, with the description "My Own WSL openSuse" and using the Windows logo as Assets. In the Visual Assets tab, it is possible to pick up an image and ask to Visual Studio generate all the other images with the required dimensions.





Any other pre-launch setup is performed in InstallDistribution() method of the DistroLauncher file. This is where distro-specific setup can be performed. As an example, the reference implementation creates a user account and sets this user account as the default for the distro.





In my case, I just comment the user step to let him to create a local user. Instead, I am creating a hard-coded user called mysuseuser:





DistributionInfo.h & DistributionInfo.cpp

You can edit your distribution-specific information in DistributionInfo.h and DistributionInfo.cpp.

In the DistributionInfo.h, you can change the DistributionInfoName variable and the DistributionInfo WindowTitle with the name of your distribution. That value will be displayed to the user via wslconfig.exe and in other places.


Notice that the DistributionInfo::Name must uniquely identify your distribution and cannot change from one version of your app to the next.





As I didn't have the usermod option to create the user, I changed the code to use useradd in the method CreateUser of the class DistributionInfo:




Build the solution

Inside the solution files, there is the build.bat file that is used to build the solution and generate the MSIX file. I am running this file in the Visual Studio Command prompt:




Follows the expected result:




Sign a MSIX package

MSIX packages must be digitally signed with a trust certificate to be installed.

If we just to install the MSIX created previously, we will receive the following error:




In our scenario, build.bat already signed the package with a self-contained certificate. This certificate is used only for testing purpose and requires to be installed on Local Machine\Trusted People of the test environment:




Windows Subsystem for Linux

Besides signing the MSIX package you have to enable WSL on your environment. As I am using Windows 11, I have enabled it from Microsoft Store:




Install for current user

Finally, after enabling WSL and signing the MSIX file, we can install it:





You can install by manually double-clicking in the msix file or using the following command:


Add-AppPackage C:\wsl\DistroLauncher-Appx_1.0.0.0_x64.msix


The Add-AppPackage command will install the MSIX app only for the current user.


Install for all users

Run the following command using an elevated account to install the MSIX app for all users:


Add-AppProvisionedPackage -Online -SkipLicense -PackagePath "C:\wsl\DistroLauncher-Appx_1.0.1.0_x64.msix"




I hope you liked it.






Version history
Last update:
‎May 20 2022 09:21 AM
Updated by: