YunoHost in WSL (Windows Subsystem for Linux)

— Everyone

Because, why not ? :slight_smile:

WSL is a nice feature of Windows 10, making Linux pseudo-distributions available through command line. I say pseudo, because they are not really like virtual machines, but they rely on virtualization capacities that make their integration with Windows almost seamless. Docker for Windows can now rely on WSL instead of Hyper-V, for example.

That last point brought me to delve into this thread’s matter. Since I was using Docker to test my YunoHost packages, why not directly use WSL to install YunoHost on it?

:warning: Bear in mind, this setup itself is not a container of any kind. If something breaks, there is no rollback capability. You may need to delete the Debian distro altogether and try again.

:warning: This setup is mainly meant for local testing. Due to limitations on WSL’s side (changing IP address, notably), selfhosting from it can be tricky and will not be described here. See the discussion below the first post.

Install Debian 10

Let’s install YunoHost into its own distro, not altering the default one. In PowerShell:

# Let's go in your home directory and prepare the working directories
cd ~
mkdir WSL
mkdir WSL\YunoHost
# Download the Debian appx package and unzip it
curl.exe -L -o
Expand-Archive .\ -DestinationPath .\debian
# Import the Debian base into a new distro
wsl --import YunoHost ~\WSL\YunoHost ~\debian\install.tar.gz --version 2
# Cleanup
rmdir .\debian -R

You can access it with wsl.exe -d YunoHost. I advise you to give a try to Windows Terminal Preview, it offers shortcuts to the WSL distros. Now, let’s open your new WSL distro. It is under Debian 9 Stretch, so let’s upgrade it:

sudo sed -i 's/stretch/buster/g' /etc/apt/sources.list`
sudo apt update
sudo apt upgrade
sudo apt dist-upgrade

Prevent WSL from tweaking configuration files

Edit /etc/wsl.conf and put the following code in it:

generateHosts = false
generateResolvConf = false

Force the use of iptables-legacy

Somehow the YunoHost post-installation does not like nf_tables, the new software replacing iptables. We can still explicitely use the good ol’ iptables though:

sudo update-alternatives --set iptables /usr/sbin/iptables-legacy
sudo update-alternatives --set ip6tables /usr/sbin/ip6tables-legacy

Install Systemd

Debian on WSL does not have systemd, a service configuration software. This is a key element for YunoHost, and any decent Debian distro (seriously MS, what the heck). Let’s install it:

  1. Install dotNET runtime:
wget -O packages-microsoft-prod.deb
sudo dpkg -i packages-microsoft-prod.deb
sudo apt update
sudo apt install -y apt-transport-https
sudo apt update
sudo apt install -y dotnet-sdk-3.1
  1. Install Genie:
# Add their repository
echo "deb [trusted=yes] /" > /etc/apt/sources.list.d/wsl-translinux.list
# Install Genie
sudo apt update
sudo apt install -y systemd-genie

Install YunoHost

# Let's switch to the root user, if you were not already
sudo su
# Initialize the Genie bottle to have systemd running
genie -s
# Your hostname should have been appended with "-wsl"
# Install YunoHost
curl | bash -s -- -a
# Perform the postinstall
yunohost tools postinstall

You will have to choose a fake domain, since it will not be accessible from outside. For example, ynh.wsl. The tricky part is advertising this domain to your host.

Alter your C:\Windows\System32\drivers\etc\hosts file. You should have a line starting by ::1, update it or add it if needed to get:

::1    ynh.wsl localhost

If you want to create subdomains, do not forget to add them in the hosts file too:

::1    ynh.wsl subdomain.ynh.wsl localhost

Access the command line

Always call genie -s while starting your distro.

wsl -d YunoHost -e genie -s


Backup and restore the distro

Make your first backup

As said before, there is no rollback capability. So let’s export your fresh distro. :slight_smile: In PowerShell:

cd ~
wsl --export YunoHost .\WSL\YunoHost.tar.gz

In case of crash, delete and restore

cd ~
wsl --unregister YunoHost
wsl --import YunoHost .\WSL\YunoHost .\WSL\YunoHost.tar.gz --version 2


  • 2020-07-04: v1
  • 2020-12-06: v2, making it a bit more like a tutorial and make the steps more explicit.



I am not even sorry. :smiling_imp: I would like to see in the future, instead of Doom, questions like “Can it run YunoHost”?

:sob: :weary: :tired_face: :see_no_evil:

Updated to look more like a tutorial. :slight_smile:


This is awesome. However currently is seems WSL 2 doesn’t support static IP addresses. So every time I restart the computer the IP address changes and that then breaks YunoHost inside of Debian WSL 2. Any good workarounds for this?

1 Like

Its very nice tutorial. Thank you for writing it down.

Have you tried what I wrote in the tutorial? If so, what is the error when you try to reach your YunoHost in WSL?
If ::1 does not work, maybe try with

Nothing shows up when I do localhost ynh.wsl or
I was getting the error in Debian ldap_sasl_bind_s(): Can’t contact LDAP server
Then I restarted everything and tried again and now I’m getting Error: Invalid usage, pass --help to see help when I type yunohost

But it’s all good I think I’ll just run YunoHost through VirtualBox for now.

What is the error in the browser? Timeout, 404 error?

I was getting that when Genie was not initialized. Restarting helps, indeed.

Well… that’s how it is supposed to work. :grinning_face_with_smiling_eyes: it means you can run commands, like yunohost tools postinstall or yunohost app install, etc.
And nothing shows up in the browser when you get this “error”?

As you wish, but it would help everyone if we can debug that together.

The error in the browser is ERR_EMPTY_RESPONSE

Sorry I should have had more of a go at this. Thanks to you pointing me in the right direction. I restarted genie and I ended up entering the WSL 2 IP address into the browser and it’s working.

However fundamentally, if I’m not mistaken, WSL 2 doesn’t support static IP addresses yet. Additionally they use subnet 172.x.x.x which means I can’t port forward from my router because my router is on 192.168.1.x subnet (hopefully I’m using all the terminology correctly, I’m still quite new to this). Basically I would want to use it to access Nextcloud and Jellyfin even when I’m not at home. Perhaps your tutorial is only meant for at home use? Or do you know of a way to use YunoHost in WSL2 and access it over WAN without having to update things every time the computer restarts?

I have one server that runs some Windows only software, but I’m also wanting to use it for YunoHost, instead of getting a second server. Hyper-V with YunoHost worked great however I had all sorts of network problems with it, so Virtual Box has so far been the best, but I really do like WSL 2 and would be keen to get it completely working, so long as it’s reliable and can be accessed over the internet.

For clarity I can use one of the dynamic DNS services that YunoHost has when I click ‘I don’t have a domain name…’ even after a computer restart the URL works over the internet which is awesome. However I’d want to use my own domain name. Looking at this reddit thread there might be some ways to achieve it so I’ll have to do some more testing.

Also after each restart I have to type in Debian WSL2
sudo -s
genie -i
Is there some way to have genie auto initialise after a computer restart?
For anyone else that’s interested I type hostname -I or ip a to find out the IP address.

Thanks for your great guide and help!

Oh yes, sorry. I meant to include that in the preamble of the tutorial.
WSL is indeed very confusing regarding the IP address assignment, as it changes at every reboot. It makes selfhosting not straightforward, and I meant this setup as a testing platform (hence the fake domain suggestion).


You can install a VPN on your YunoHost for WSL. Currently I use ZeroTier (free for personal usage, non-free license though, hence why it is not listed in the catalog). I am investigating WireGuard but it seems it would require changing WSL’s kernel.

It is not as straightforward as having a real server, but it would allow you to circumvent the issue with changing IPs.

Yes. Execute shell:startup (in the Win+R dialog) to reach the startup folder. Then create a shortcut to wsl with the right arguments. wsl.exe -d YunoHost -e genie -s (something like that, I cannot make it work right now)