AOSC Wiki / AOSC OS / Installation Guides / .
Also available in: 简体中文


Installing AOSC OS on Windows Subsystems for Linux

It is surprisingly easy to run AOSC OS on Windows Subsystems on Linux.


WSL comes in two flavors:

You naturally need to first enable WSL to proceed. Read Microsoft's guide on how.

Choosing a tarball§

As of the time of writing, WSL is only supported on AMD64 devices. Please check the section in the AMD64 Guide.

Unpacking the tarball§

LxRunOffline is a great tool for managing WSL installs. Among other things that Microsoft does not yet provide, it:

After you have download the tarball and the tool, run the following in PowerShell:

# Unpack the distro (avoid using a name with spaces!)
& ".\LxRunOffline.exe" install `
  -n AOSC-Whatever `
  -d C:\path\to\the\target `
  -f C:\path\to\the\tarball `

Note: as is the case for any type of installation, you can greatly speed up the process by temporarily disabling your antivirus or by adding the target directory to an exclusion list.

Now that the OS is known to WSL, you can start it using any of the usual ways: with LxRunOffline, in a new tab in Windows Terminal, or using the desktop shortcut that has just been created.

Setting up your system§

Some more configuration is needed for the WSL system to interoperate with Windows properly. Enter a root shell in the new WSL instance of AOSC OS and run:

# Remove /etc/resolv.conf so WSL can generate it for us
rm /etc/resolv.conf
# Put sane defaults in /etc/wsl.conf
cat > /etc/wsl.conf << 'EOF'
options = "metadata,umask=22,fmask=11"
# Leave setting PATH to WSL so appends will work
sed -e '/^unset PATH MANPATH/d' \
    -i /etc/profile

Now exit the shell and re-open it. You should have a functional, if a bit unorthodox, system available. Continue to the User, and Post-installation Configuration section of the AMD64 guide.

LxRunOffline cannot create WSL2 instances. You may convert the WSL1 instance to WSL2 using wsl --set-version AOSC-Whatever 2 (MS documentation). Note that you need to keep the installation path uncompressed and unencrypted, or you may get an error while creating the VHDX file.

Any more plumbing needed?§

Sadly, yes.

Apparently we need [Xvnc and a heavily modified version of systemd]( for a graphical login screen. Add that to the packaging list.
Windows Store
We will eventually need to provide gzipped tarballs when we want to submit AOSC OS to Windows Store. Unless Microsoft [gets its act together](, that is.
And we better fix the ugly `/etc/profile` hack before we submit. Not that Microsoft cares.