This page explains how to create a simple Kivy “Hello world” program. This assumes you already have Kivy installed. If you do not, head over to the Installation section. We also assume basic Python 2.x knowledge throughout the rest of this documentation.

Create an application

The base code for creating an application looks like this:

import kivy
kivy.require('1.0.6') # replace with your current kivy version !

from kivy.app import App
from kivy.uix.button import Button

class MyApp(App):
    def build(self):
        return Button(text='Hello World')

if __name__ == '__main__':

Save it as main.py.

To run the application, follow the instructions for your operating system:


Follow the instructions for running Kivy application on Linux:

$ python main.py

Follow the instructions for running Kivy application on Windows:

$ python main.py
# or
C:\appdir>kivy.bat main.py
Mac OS X

Follow the instructions for running Kivy application on MacOSX:

$ kivy main.py
Your application needs some complementary files to be able to run on Android. See Kivy on Android for further reference.

A window should open, showing a sole button (with the label ‘Hello World’) that covers the entire window’s area. That’s all there is to it.


So what does that code do?

  1. First, we import Kivy, and check if the current installed version will be enough for our application. If not, an exception will be automatically fired, and prevent your application to crash in runtime. You can read the documentation of kivy.require() function for more information.
  2. We import the App class, to be able to subclass it. By subclassing this class, your own class gains several features that we already developed for you to make sure it will be recognized by Kivy.
  3. Next, we import the Button class, to be able to create an instance of a button with a custom label.
  4. Then, we create our application class, based on the App class. We extend the build() function to be able to return an instance of Button. This instance will be used as the root of the widget tree (because we returned it).
  5. Finally, we call run() on our application instance to launch the Kivy process with our application inside.