How to Use

In this guide you will learn how to setup and use Kivy Reloader for your projects.

Project structure

Select the app structure below according to your experience level: beginner, intermediate, or advanced.

Beginner exampleIntermediate ExampleAdvanced Example

If you are a beginner in Kivy, we will show you a complete app made using only one file.

├── main.py

Create a file main.py and paste this code:

import trio
from kivy.lang import Builder

from kivy_reloader.app import App

kv = """
Button:
    text: "Hello World"
"""


class MainApp(App):
    def build(self):
        return Builder.load_string(kv)


app = MainApp()
trio.run(app.async_run, "trio")

How to use Kivy Reloader

In the project folder, type in the terminal kivy-reloader init.

$ kivy-reloader init

This is going to create two files on your project folder: kivy-reloader.toml and buildozer.spec.

Configure kivy-reloader.toml:

The first time you run kivy-reloader init, you will see on the terminal:

This is the kivy-reloader.toml that has been created on your project folder.

Every line has an explanation above. The most important constants on this file are:

1. PHONE_IPS: Put the IP of your phone here. You can find the IP of your Android phone on: Settings > About phone > Status > IP Address.

1. HOT_RELOAD_ON_PHONE: Set it to True to hot reload on your phone when you press Ctrl + S
2. FULL_RELOAD_FILES: This is a list of file names (relative paths) that will trigger a live reload (your Kivy app will restart) when they change. In this beginner example, we are watching only the main.py file, and when we change it, the app will restart.
3. WATCHED_FOLDERS_RECURSIVELY: This is a list of folder names (relative paths), in this beginner example it is [] (empty list). This is because we are not watching any folder, we're only watching main.py. Check the Advanced Example to see how to watch folders.

[kivy-reloader]

PHONE_IPS = ["192.168.1.71"] # Replace with your phone IP

HOT_RELOAD_ON_PHONE = true

FULL_RELOAD_FILES = ["main.py"]

WATCHED_FOLDERS_RECURSIVELY = []

The kivy-reloader init also creates a file called buildozer.spec on your project folder. It has the minimal buildozer.spec that you can use to make your app work with Kivy Reloader on Android.

Pay attention to the folder names

Note that the Reloader will only watch for changes on the files inside the folders you specify. For example, if you want that a change in any file inside the folder screens to cause a hot reload, you must specify the folder screens on the WATCHED_FOLDERS_RECURSIVELY list.

Pay attention to the name of the folders that you want the Reloader to watch. It will not work if you don't do it correctly.

• Create a file called main.py, a file called app.py and a folder called screens.

• Inside the screens folder, create two files: main_screen.kv and main_screen.py

.
├── main.py
├── app.py
└── screens
    ├── main_screen.kv
    └── main_screen.py

import trio

from app import MainApp

app = MainApp()
trio.run(app.async_run, "trio")

from kivy_reloader.app import App
from screens.main_screen import MainScreen

class MainApp(App):
    def build(self):
        return MainScreen()

<MainScreen>:
    BoxLayout:
        orientation: 'vertical'
        Button:
            text: 'Welcome to Kivy Reloader!'

import os

from kivy.uix.screenmanager import Screen

from kivy_reloader.utils import load_kv_path

main_screen_kv = os.path.join("screens", "main_screen.kv")
load_kv_path(main_screen_kv)


class MainScreen(Screen):
    pass

How to use Kivy Reloader

In the project folder, type in the terminal kivy-reloader init.

$ kivy-reloader init

This is going to create two files on your project folder: kivy-reloader.toml and buildozer.spec.

Configure kivy-reloader.toml:

The first time you run kivy-reloader init, you will see on the terminal:

This is the kivy-reloader.toml that has been created on your project folder.

Customize the kivy-reloader.toml

Every line has an explanation above. The most important constants on this file are:

1. PHONE_IPS: Put the IP of your phone here. You can find the IP of your Android phone on: Settings > About phone > Status > IP Address.

1. HOT_RELOAD_ON_PHONE: Set it to True to hot reload on your phone when you press Ctrl + S
2. FULL_RELOAD_FILES: This is a list of file names (relative paths) that will trigger a live reload (your Kivy app will restart) when they change. In this intermediate example, we want to restart the app when main.py or app.py changes. So, in this example, set this: FULL_RELOAD_FILES = ["main.py", "app.py"]
3. WATCHED_FOLDERS_RECURSIVELY: This is a list of folder names (relative paths) that will cause a hot reload if any file inside them changes. In this example it is ["screens"]. This means that a change in any file inside the screens folder will trigger a hot reload.

This is the final kivy-reloader.toml that you will use in this example:

[kivy-reloader]

PHONE_IPS = ["192.168.1.100"] # Replace with your phone IP

HOT_RELOAD_ON_PHONE = true

FULL_RELOAD_FILES = ["main.py", "app.py"]

WATCHED_FOLDERS_RECURSIVELY = ["screens"]

The kivy-reloader init also creates a file called buildozer.spec on your project folder. It has the minimal buildozer.spec that you can use to make your app work with Kivy Reloader on Android.

Pay attention to the folder names

Note that the Reloader will only watch for changes on the files inside the folders you specify. For example, if you want that a change in any file inside the folder screens to cause a hot reload, you must specify the folder screens on the WATCHED_FOLDERS_RECURSIVELY list.

Pay attention to the name of the folders that you want the Reloader to watch. It will not work if you don't do it correctly.

This is the recommended way of structuring your app.

• Create a file called main.py and a folder called beautifulapp.

• Inside the beautifulapp folder, create a file called __init__.py.

• Inside the beautifulapp folder, create a folder called screens.

• Inside the screens folder, create two files: main_screen.kv and main_screen.py

.
├── beautifulapp
│   ├── __init__.py
│   └── screens
│       ├── main_screen.kv
│       └── main_screen.py
├── main.py

import trio

from beautifulapp import MainApp

app = MainApp()
trio.run(app.async_run, "trio")

from beautifulapp.screens.main_screen import MainScreen
from kivy_reloader.app import App


class MainApp(App):
    def build(self):
        return MainScreen()

<MainScreen>:
    BoxLayout:
        orientation: 'vertical'
        Button:
            text: 'Welcome to Kivy Reloader!'

import os

from kivy.uix.screenmanager import Screen

from kivy_reloader.utils import load_kv_path

main_screen_kv = os.path.join("beautifulapp", "screens", "main_screen.kv")
load_kv_path(main_screen_kv)


class MainScreen(Screen):
    pass

How to use Kivy Reloader

In the project folder, type in the terminal kivy-reloader init.

$ kivy-reloader init

This is going to create two files on your project folder: kivy-reloader.toml and buildozer.spec.

Configure kivy-reloader.toml:

The first time you run kivy-reloader init, you will see on the terminal:

This is the kivy-reloader.toml that has been created on your project folder.

Customize the kivy-reloader.toml

Every line has an explanation above. The most important constants on this file are:

1. PHONE_IPS: Put the IP of your phone here. You can find the IP of your Android phone on: Settings > About phone > Status > IP Address.

1. HOT_RELOAD_ON_PHONE: Set it to True to hot reload on your phone when you press Ctrl + S
2. FULL_RELOAD_FILES: This is a list of file names (relative paths) that will trigger a live reload (your Kivy app will restart) when they change. In this advanced example, we want to restart the app when main.py or beautifulapp/__init__.py changes. So, in this example, set this: FULL_RELOAD_FILES = ["main.py", "beautifulapp/__init__.py"]
3. WATCHED_FOLDERS_RECURSIVELY: This is a list of folder names (relative paths) that will cause a hot reload if any file inside them changes. In this example it is ["beautifulapp"]. This means that a change in any file inside the beautifulapp folder will trigger a hot reload.

This is the final kivy-reloader.toml that you will use in this example:

[kivy_reloader]

PHONE_IPS = ["192.168.1.71"] # Replace with your phone IP

HOT_RELOAD_ON_PHONE = false

FULL_RELOAD_FILES = ["main.py", "beautifulapp/__init__.py"]

WATCHED_FOLDERS_RECURSIVELY = ["beautifulapp"]

The kivy-reloader init also creates a file called buildozer.spec on your project folder. It has the minimal buildozer.spec that you can use to make your app work with Kivy Reloader on Android.

Pay attention to the folder names

Note that the Reloader will only watch for changes on the files inside the folders you specify. For example, if you want that a change in any file inside the folder beautifulapp to cause a hot reload, you must specify the folder beautifulapp on the WATCHED_FOLDERS_RECURSIVELY list.

Pay attention to the name of the folders that you want the Reloader to watch. It will not work if you don't do it correctly.

Run your app

Type python main.py on the terminal and your app will start. You can see the logs on the terminal.

python main.py

When you change any file (from the watched folders you specified on the kivy-reloader.toml file), your app will reload.

How to compile and hot reload on Android:

Kivy Reloader uses Buildozer to compile your app and deploy it on your Android phone. Before using Buildozer, you need to install several dependencies that are necessary for building and deploying your Kivy app on Android.

What is Buildozer

Buildozer automates the entire build process, download prerequisites like python-for-android, Android SDK, NDK, etc.

Buildozer manages a file named buildozer.spec in your application directory, describing your application requirements and settings such as title, icon, included modules etc. It will use the specification file to create a package for Android, iOS, and more.

Install Buildozer dependencies

UbuntumacOS

$ sudo apt install -y git zip unzip openjdk-17-jdk autoconf libtool pkg-config zlib1g-dev libncurses5-dev libncursesw5-dev libtinfo5 cmake libffi-dev libssl-dev

1. Connect your phone to the computer using a USB cable.
2. Enable developer options and enable USB debugging on your phone.
3. In VS Code, use the + arrow to add a Command Prompt or Powershell terminal (doesn't matter which one). You just need to run your PC and Android client at the same time.

   

   

4. In the right terminal, type to run your PC client:

   $ python main.py
   

5. On the left terminal, type kivy-reloader run:

   $ kivy-reloader run
   

   

   What this CLI application does?

   • Compile your app (generate .apk file) and deploy it on your Android phone.
   • Start adb logcat and filter the logs from your app on the terminal.
   • Start scrcpy to mirror your phone screen on your computer.
   • Create a .aab file that will be used to deploy your app on Google Play Store.
   • Restart the adb server for you if needed (to fix issues with adb).

   You can easily control the CLI application using ↑ or ↓ arrows, and press ENTER ↵ or → to select the option you want.

6. Choose the first option and Buildozer will compile the app (create a .apk file) and deploy it on your phone. Once the app is on your phone, run python main.py and the hot reload will be already working.

Just press Ctrl + S in any file inside screens folder or main.py and your app will be updated on computer and phone at the same time. (assuming you have configured the kivy-reloader.toml file correctly).

We need someone to test the macOS installation instructions. If you have a macOS system and never installed Buildozer before, please, help us to improve this section. Enter in contact with #filipemarch at Discord.

1. Connect your phone to the computer using a USB cable.
2. Enable developer options and enable USB debugging on your phone.
3. In VS Code, use the + arrow to add a Command Prompt or Powershell terminal (doesn't matter which one). You just need to run your PC and Android client at the same time.

   

   

4. In the right terminal, type to run your PC client:

   $ python main.py
   

5. On the left terminal, type kivy-reloader run:

   $ kivy-reloader run
   

   

   What this CLI application does?

   • Compile your app (generate .apk file) and deploy it on your Android phone.
   • Start adb logcat and filter the logs from your app on the terminal.
   • Start scrcpy to mirror your phone screen on your computer.
   • Create a .aab file that will be used to deploy your app on Google Play Store.
   • Restart the adb server for you if needed (to fix issues with adb).

   You can easily control the CLI application using ↑ or ↓ arrows, and press ENTER ↵ or → to select the option you want.

6. Choose the first option and Buildozer will compile the app (create a .apk file) and deploy it on your phone. Once the app is on your phone, run python main.py and the hot reload will be already working.

Just press Ctrl + S in any file inside screens folder or main.py and your app will be updated on computer and phone at the same time. (assuming you have configured the kivy-reloader.toml file correctly).