Skip to content

Kivy Reloader in Windows WSL2 targeting Android devices

Instructions are done! Feel free to view the canva link and you will get a complete tutorial on setting up Windows and WSL2 to target Android devices.

Canva Public View Link

Here you will learn how to set up WSL2 and prepare your Windows machine to develop Kivy apps for Android.

Then, you can continue the original Kivy Reloader on Linux tutorial and follow everything step by step within WSL2.

This is only required if you want to create a Kivy app for Android since Buildozer needs WSL2.

If you want to develop a Windows app ONLY with Kivy

If you want to develop a Windows app ONLY with Kivy, you do not need WSL2 and can follow the original Kivy Reloader on Windows tutorial step by step.

GitHub Repository for Kivy Reloader

Kivy Reloader Showcase Windows WSL2 Targeting Android

Prerequisites:

You need:

  • A real Android phone
  • USB cable
  • Updated Windows 10 OR Windows 11

What you will install

  • ✔️ VS Code on Windows with WSL extension
  • ✔️ WSL2
    • ✔️ Git in WSL2
    • ✔️ pyenv in WSL2
    • ✔️ python in WSL2
    • ✔️ poetry in WSL2
    • ✔️ scrcpy in WSL2
      • scrcpy automatically installs ✔️ adb
  • ✔️ Chocolatey in Windows
    • ✔️ install scrcpy in Windows through Chocolatey
      • (scrcpy automatically installs ✔️ adb on Windows as well)
  • Optionally:
    • ❓ VcXserv for native Windows look on WSL apps instead of WSLg

How to install WSL2

Microsoft instructions for installing WSL

Prerequisites:

You must be running Windows 10 version 2004 and higher (Build 19041 and higher) or Windows 11 to use the commands below. If you are on earlier versions please see the manual install page.

WSL MANUAL INSTALL LINK FOR OLD WINDOWS 10 VERSIONS

This tutorial assumes you have an updated Windows version 10 or Windows 11. If you do not, please update your Windows version and avoid suffering.

What is WSL2?

WSL means Windows Subsystem for Linux. This means that you can access the power of Linux and Windows running on the same machine.

In the Kivy for Android context, Buildozer is maintained by the core Kivy developers only on Linux builds targeting Android.

Buildozer is only tested with WSL2. (As of Aug 2024, does NOT work with WSL1)

Instead of making a new Linux partition, we will use the official Microsoft solution and enable WSL2.

How do I install WSL2?

Step 1: Open PowerShell or Command Prompt in Administrator mode

Step 2: Install WSL2 in Admin Powershell

  • Execute this in your Admin PowerShell/CMD 
    $ wsl --install

(Step 2 Optional) Choose your Linux distribution

Step 2 (optional): Choose your Linux distribution

By default, wsl --install installs Ubuntu. If you want another Linux distribution, you can see the list with:

$ wsl -l -o

You can then install the version you want with

$ wsl --install -d DistributionName

Step 3a Restart your machine

Step 3b Set your user info

  • Reminder that in Linux, your keystrokes are recorded but NOT displayed with ***** so be careful what you type in!

If you forget your Linux user/password (click this bar to open instructions) 

$ wsl -u root


$ passwd <username>

You will be prompted to enter a new UNIX password and then confirm that password

Exit WSL in Powershell:

$ exit

  • OPTION 2: Manual backup and reset

  • If you forget your Linux user/password, make sure to back up your files and uninstall WSL2 and reinstall again, or else you will lose all your progress.

Step 4 Check that you are running WSL2

  • In Command Prompt, type:

$ wsl -l -v

For Buildozer to work, you MUST use WSL2!

Step 5 Update your drivers

NVDIA driver example

  • Get on the NVIDIA driver website.

  • Go on task manager and copy your GPU stats

  • For NVIDIA, you want to get the "Game Ready Driver" or "NVIDIA Studio Driver" (They are effectively the same, the "Game Ready Driver" updates more frequently to match big game releases.)

(Step 6 Optional) Further Reading

If you want to learn more:

Microsoft Guide to setting up WSL environment

Important notes:

How to install Chocolatey

What is Chocolatey?

Chocolatey is a package manager for Windows. Chocolatey AVOIDS having MULTIPLE BROKEN INSTALLS OF SOFTWARE that happens when doing manual installs.

Chocolatey automatically adds installed programs to PATH.

Choco also uninstalls apps cleanly, no need to find an uninstall guide.

You also do not have to remember where you manually install software.

Also has the useful refreshenv command so you don't have to keep reopening CMD/Powershell when you update PATH. Just type refreshenv and PATH will automatically update.

Warning

If you can use Chocolatey for a package, you SHOULD.

How do I install Chocolatey?

Chocolatey install reference

Step 1 Check that Get-ExecutionPolicy is NOT Restricted

  • Open PowerShell in Administrator mode

  • Type:

$ Get-ExecutionPolicy

  • If it returns Restricted, run:

$ Set-ExecutionPolicy Bypass -Scope Process

  • Type Y and press Enter to accept.

Step 2 Install Chocolatey

  • Run this command in your Admin PowerShell:

$ Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))

Step 3 Wait for installation to complete

Step 4 Verify installation

  • Type:

$ choco

OR

$ choco -?

Install scrcpy through Chocolatey

How do I Install scrcpy (Screen Copy) through Chocolatey?

  • Chocolatey scrcpy package link

  • Scrcpy lets you mirror your Android phone through desktop.

  • Scrcpy will also install adb for you! If you need to manually install adb, the instructions are in the next section.

Step 1: Install scrcpy through Choco

  • Type:

$ choco install scrcpy

  • Type Y for "yes to all"

Step 1b: make sure adb (android debug bridge) got installed with scrcpy

  • Type adb in Windows to confirm adb installation: 

$ adb

Step 2: make sure scrcpy is installed

  • Open a new Command Prompt (or type refreshenv) and type:

$ scrcpy

  • scrcpy should complain because your phone is not connected yet.

  • If there are no errors, proceed to the next step!
How do I Install ADB (Android Debug Bridge) through Chocolatey?

scrcpy should automatically install adb for you, but if you need to install adb manually, here are the steps to do it in Chocolatey

Step 1: Open PowerShell in Administrator mode

Step 2: Make sure choco is installed

  • Type:

$ choco

OR

$ choco -?

Step 3: Install adb

  • Type

$ choco install adb

  • Type Y for "yes to all"

Step 4: Make sure adb is installed

  • Open a new Command Prompt (or type refreshenv) and type:

$ adb

  • If there are no errors, proceed to the next step!

Set up VSCode for WSL2

How do I set up VSCode for WSL2?

Step 1: Install VSCode for Windows

Step 1b: Install WSL Extension for VSCdoe

  • The WSL extension lets you code using your Windows VSCode and use the WSL virtual environment.

  • Select the Extensions icon

  • In extensions, type WSL

  • Select Install

Setting up your Ubuntu WSL2 Installation

Preparing your WSL2 install to handle Kivy projects

Next we will follow the Ubuntu installation on kivyschool.com with changes to make it work for WSL.

We will install these programs in WSL. Reminder that even if you have these programs installed in your host Windows, they will not be installed in your WSL Ubuntu side!

  • Git
  • pyenv
  • Python
  • poetry
How do I prepare WSL for Kivy projects?

These steps will be mostly the same as the Ubuntu install with a few notable exceptions, mainly the pyenv export so that WSL pyenv does not try to use the Windows pyenv.

WSL: Step 1: Update WSL, source ~/.bashrc and install Git

Step 1: How do I update WSL, source ~/.bashrc and install Git?

Step 1: Open WSL

  • Press the ⊞ Windows key and type wsl

OR

  • Open Command Prompt and type wsl

Step 1b: Update WSL

In your WSL terminal, make sure WSL is updated:

$ sudo apt-get update

note: The terminal is grey because WSL ubuntu-22.04 does not automatically source ~/.bashrc but ubuntu-24.04 does automatically source ~/.bashrc.

Step 1c: Source ~/.bashrc

  • Run Bashrc file by typing:

$ bash

OR

$ source ~/.bashrc

Step 1d: check if Git is installed

$ git --version

If Git is not installed, install it.

$ sudo apt-get install git

Check if Git is installed again:

$ git --version

WSL: Step 2: Install Buildozer build dependencies

Step 2: How do I install Buildozer build dependencies?

Step 2: Install Buildozer build dependencies

Reference link: buildozer docs

$ sudo apt install zip unzip openjdk-17-jdk cmake autoconf libtool pkg-config build-essential libssl-dev zlib1g-dev libbz2-dev libreadline-dev libsqlite3-dev curl libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev libncurses5-dev

Optionally, you can also install the legacy library libtinfo5 (does not exist in Ubuntu 24.04 but does exist in Ubuntu 22 and Ubuntu 20)

$ sudo apt install libtinfo5

Quick library overview:

  • zip/unzip: for zipping/unzipping, in case you don't have it.
  • openjdk-17-jdk: for building with java
  • autoconf: auto configure files
  • libtool pkg-config build-essential libssl-dev zlib1g-dev libbz2-dev libreadline-dev libsqlite3-dev curl libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev: required for building with buildozer
  • libncurses5, libtinfo5: legacy libraries (buildozer may work without these)

WSL2: Step 3: Install and Configure Pyenv

Step 1: How do I Install and Configure Pyenv?

Reference: Kivy School Ubuntu Installation

Step 3a: Install Pyenv

$ git clone https://github.com/pyenv/pyenv.git ~/.pyenv

Step 3b: make Pyenv

$ cd ~/.pyenv && src/configure && make -C src

Step 3c: add pyenv to PATH

$ echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc
$ echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc
$ echo 'eval "$(pyenv init -)"' >> ~/.bashrc

User Report! On step "Step 3c: add pyenv to PATH"

From @Monochromatic:

On step "WSL2: Step 3: Install and Configure Pyenv" -> Step 3c: add pyenv to PATH

Whenever I would then try to source .bashrc it would tell me something along the lines of "no permissions, line 73 in .bashrc"

After looking at the file and said line, it uses the variable $PWD that when I printed it, instead of giving me /home/[user name] it was giving root.

What the problem was: For whatever reason everytime I install WSL it always gets stuck at the command line window saying "This may take a few minutes.....", no matter how long I leave it, it never continues so after a while I just closed it and restarted the machine.

Turns out that Ubuntu was installed fine but since it stuck on that stage I never got to the stage where it prompts you to create a user.

So I created a user manually and I just did su [username] everytime to log in my user. BUT, turns out that this doesn't change the $PWD variable, so what I had to do was edit the /etc/wsl.conf file and add this at the start

$ [user]
$ default=[myusername]

I might have edited another file for permissions but I don't remember now.

Anyway, this is obviously not an error with the guide itself, just a sidenote for people that might encounter the same problem as me and don't know why they can't get past step 3. I still have no idea why the WSL installer is getting stuck at the same place everytime

Step 3d: check pyenv is installed

Close the terminal and open it again OR source ~/.bashrc

Do not forget this step or else you WILL see an error.

  • Type 

$ pyenv --version

  • If you see something like pyenv 2.3.14, you have successfully installed Pyenv.

WSL2: Step 4: Install Python using Pyenv

Step 4: How do I Install Python using Pyenv?

Step 4: Install Python using Pyenv

  • Type pyenv install 3.10.9 (you can install any Python version you want)

$ pyenv install 3.10.9

Step 4b: check Python version

  • Type 

$ pyenv versions

  • This will show you all the Python versions you have installed with Pyenv.

Step 4c: set global Python version

  • Type 

$ pyenv global 3.10.9

  • This will set the global Python version to 3.10.9.

Step 4d: check global Python version

  • Type 

$ python --version

  • If you see Python 3.10.9, you have successfully set the global Python version to 3.10.9.

WSL2: Step 5: Install and configure Poetry

Step 5: How do I install and configure Poetry?

Step 5a: Install Poetry

  • Type to install Poetry:

$ curl -sSL https://install.python-poetry.org | python3 -

Step 5b: Add Poetry to PATH

  • Type to add Poetry to PATH:

$ echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc

Step 5c: check Poetry installation

Close the terminal and open it again OR source ~/.bashrc

Do not forget this step or else you WILL see an error.

  • Type 

$ poetry --version

  • If you see something like Poetry version 1.4.0, you have successfully installed Poetry.

Step 5d: Poetry Configuration

  • Type 

$ poetry config virtualenvs.in-project true

  • This will set the virtual environment to be created in the project folder.

Step 5e: Poetry Configuration

  • Type 

$ poetry config virtualenvs.create true

  • This will set the virtual environment to be created automatically when you run poetry install.

WSL2: Step 6: Install latest scrcpy on WSL

Step 6: How do I install scrcpy on WSL?

Step 6: Install scrcpy on WSL

  • Reference: scrcpy documentation

  • For Ubuntu at the time of writing, scrcpy from apt is not yet the latest version, so we have to get it manually.

  • In WSL, type to install the required build packages:

$ # for Debian/Ubuntu
$    sudo apt install ffmpeg libsdl2-2.0-0 adb wget \
$             gcc git pkg-config meson ninja-build libsdl2-dev \
$             libavcodec-dev libavdevice-dev libavformat-dev libavutil-dev \
$             libswresample-dev libusb-1.0-0 libusb-1.0-0-dev

  • Next, cd to home directory:

$ cd ~

  • Clone the repo and run the installer

$ git clone https://github.com/Genymobile/scrcpy
$ cd scrcpy
$ ./install_release.sh

To update or uninstall scrcpy on WSL:

  • To update:

  • cd to scrcpy folder (if you followed instructions it should be cd ~/scrcpy)

$ cd ~/scrcpy

  • Then update repo and reinstall scrcpy.

$ git pull
$ ./install_release.sh

  • To uninstall:

  • cd to scrcpy folder (if you followed instructions it should be cd ~/scrcpy)

$ cd ~/scrcpy

  • Run the uninstaller:

$ sudo ninja -Cbuild-auto uninstall

How do I install adb on WSL?

scrcpy should automatically install adb for you, but if you need to install adb manually, here are the steps to do it in WSL Ubuntu

How to install adb

  • Type to install adb in WSL:

$ sudo apt-get install adb

  • This will install android debug tools (adb) in WSL.

  • Type to adb to check for proper installation:

$ adb

WSL2: Step 7 (OPTIONAL): Install and Configure VcXsrv

Step 7: Why should I Install and Configure VcXsrv for WSL?

WSLg is the default window provider.

  • PRO:

    • Preinstalled with WSL

  • CON:

    • It's ugly (subjective).

VcXsrv is basically a native window.

  • PRO:

    • It looks good

  • CON:

    • You might confuse Windows apps with WSL apps when developing
    • More installation work

Step 7 (OPTIONAL): How do I Install and Configure VcXsrv for WSL?

Step 1: turn off WSLg

  • Reference: reddit post

  • You need to turn off WSLg since it takes priority over VcXsrv

  • Make a .wslconfig file in %UserProfile% directory

  • Example: C:\Users\Pengin\.wslconfig

  • Add this in the .wslconfig file

$ [wsl2]
$ guiApplications=false

  • Restart WSL in CMD

$ wsl --shutdown


$ wsl

Step 2: Install VcXsrv

  • Install VcXsrv through github

  • Get the regular release that has 64 and installer in it.

  • Skip debug

  • Skip noadmin

  • Get 64 if you have a x64 bit PC (most modern computers are this)

  • If you have x32 get the one that DOESN'T say 64 (older computers and budget computers are x32)

  • Run the installer

  • Windows will protect your PC

  • Click More info > run anyway

  • Click Yes to install

  • Defaults are OK

  • Click Next

  • Defaults are OK

  • Click Install

  • Installing...

  • Go to where you installed VcXsrv
  • Start xlaunch.exe
  • Click Next

  • Default is OK
  • Click Next

  • Check Disable Access Control
  • Click Next

DO NOT CLICK FINISH YET

  • Click Save configuration

  • Save the .launch profile on your Desktop

  • Name it KivyWSL.xlaunch

  • Click Finish

  • Now you will have KivyWSL.xlaunch on your Desktop

If you want to see a GUI application when running WSL2, you NEED to run KivyWSL.xlaunch

You NEED to run KivyWSL.xlaunch. This is especially true because WSLg is also disabled (so there is no backup window provider).

If you want to go back to WSLg, simply remove the .wslconfig file created earlier.

  • When you run you might get a firewall alert, just enable on Private and Public networks, otherwise you will have to do it manually later (using wf.msc)

  • You will know VcXsrv is running when you click on the system tray and see a VcXsrv icon

Every time you want a window from WSL you must run the launch config.

You have two options:

  • Add a shortcut on windows desktop which this tutorial has provided you
  • Add that config to Windows startup

Step 3: Update WSL and export display to send to VcXsrv

$ echo 'export DISPLAY=$(grep -m 1 nameserver /etc/resolv.conf | awk "{print \\$2}"):0.0' >> ~/.bashrc

  • The command has been modified to work correctly with export. This lets WSL find your Windows IP and send display information to VcXsrv on your Windows machine
  • This is because WSL2 does not share the localhost of your Windows machine.

  • In WSL1 you could just do export DISPLAY=localhost:0.0 BUT WSL1 is not compatible with Buildozer

  • This should be in your ~/.bashrc file:

  • Remember to source ~/.bashrc or bash to update your WSL terminal!

Step 4: Allow VcXsrv in Windows Defender Firewall

$ wf.msc

  • Go to Inbound Rules
  • Make sure VcXsrv is allowed on everything

WSL2: Step 8 (OPTIONAL): Proper Git setup for WSL

Step 8 (OPTIONAL): How do I configure Git in WSL? 

$ git config --global credential.helper manager

  • older Git versions, in Windows CMD

$ git config --global credential.helper manager-core

  • Make sure that GCM is used by Git on your host Windows.

  • To use GCM from Windows on your WSL install, type the correct command:

  • If GIT installed is >= v2.39.0, in WSL terminal

$ git config --global credential.helper "/mnt/c/Program\ Files/Git/mingw64/bin/git-credential-manager.exe"

  • else if GIT installed is >= v2.36.1, in WSL terminal

$ git config --global credential.helper "/mnt/c/Program\ Files/Git/mingw64/libexec/git-core/git-credential-manager.exe"

  • else if version is < v2.36.1 enter this command, in WSL terminal

$ git config --global credential.helper "/mnt/c/Program\ Files/Git/mingw64/bin/git-credential-manager-core.exe"

Recap:

By the end of this tutorial, you will have:

  • ✔️ Real Android phone
  • ✔️ USB cable
  • ✔️ VS Code on Windows with WSL extension
  • ✔️ WSL2
    • ✔️ Git
    • ✔️ pyenv
    • ✔️ Python (installed through pyenv)
    • ✔️ poetry
    • ✔️ scrcpy in WSL2
      • scrcpy automatically installs ✔️ adb
  • ✔️ Chocolatey in Windows
    • ✔️ install scrcpy in Windows through Chocolatey
      • (scrcpy automatically installs ✔️ adb on Windows as well)
  • Optionally:
  • ❓ VcXsrv for native Windows instead of WSLg

🎉 Congratulations! 🎉 Now it is time to learn how to use kivy-reloader on WSL.

🎉 Congratulations! 🎉 Now it is time to learn how to use kivy-reloader on WSL.

Click here to learn how to install and use kivy-reloader!

Closing notes: Tips for first time WSL users

Tips for first time WSL users.

  • Always source ~/.bashrc (in WSL Ubuntu 24.04 this is done for you)

  • Every time you enter WSL and the terminal has no color, you must manually update the terminal.

  • Type: bash or source ~/.bashrc

$ bash


$ source ~/.bashrc

  • If you do not source ~/.bashrc or it is not automatically sourced for you, NOTHING WILL WORK.

  • WSL2 Ubuntu24.04 automatically sources ~/.bashrc from experience

If you installed VcXsrv but no window shows.

  • Remember to turn on KivyWSL.xlaunch if you have VcXsrv installed so your WSL apps show up on your Windows desktop.
Useful commands to know in WSL/Linux:
  • How to make a directory:

$ mkdir foldername

  • How to remove a folder recursively:

$ rm -r foldername

Contribution

If you have any idea or suggestion, please open an issue or a pull request.

Do you need help?

If you need help with Kivy Reloader, you can ask on Kivy Discord support channels. We'll be happy to help you.

Article Error Reporting

Message @BadMetrics on the Kivy Discord.