Getting Started¶
Introduction¶
Creating Kivy apps is fun and rewarding. This guide should be the perfect starting point to get you on the right track for app development. You will require a basic knowledge of Python to follow this introduction.

If you need more background about Python language, you might be interested in these tutorials:
Using Kivy on your computer, you can create apps that run on:
- Desktop computers: MacOSX, Linux, Windows.
- iOs Devices: iPad, iPhone
- Android devices: Tablets, phones.
- Any other touch-enabled professional/homebrew devices supporting TUIO (Tangible User Interface Objects).
Kivy empowers you with the freedom of writing your code once and having it run as-is on different platforms.
Follow this guide to get the tools you need, understand the major concepts and learn best practices. As this is an introduction, pointers to more information will be provided at the end of each section.
As you proceed through the guide, you will, using Kivy:
- Learn: The basics of programming with the Kivy language.
- Explore: The Kivy framework.
- Create: simple cross-platform app.
- Package: for your choice of platform.
Finally, you will learn how to Deploy on a device of your choice.
Each section of the guide introduces a new topic, trying to give you enough information to get started and links to related articles for more in-depth explanations. When you are done with this guide, you’ll be able to develop Kivy apps and you will know where to look for information for the more challenging stuff your innovative applications will require.
Enough introductions, let’s get down to business.
Installation¶
With Kivy, you can use your favourite development environment to start coding your App. To get started, you need to download the latest version of Kivy:
After download, please refer to the installation instructions for your specific platform:



Development Version
If you want the development version of Kivy, so you can use the latest additions to the framework, you can get the source code from github:
git clone http://github.com/kivy/kivy
Take a look at our instructions on installation of the Development Version
A first App¶
Immerse yourself in the world of Kivy with your first App.

The Pong Game Tutorial introduces the fundamental design patterns and the application development process. As you follow the tutorial, you will create a simple app. You will also learn how to run the app on your OS. The simple steps in the tutorial introduce elegant, useful concepts that you will use over and over again in app development.
The Pong Game Tutorial is the most important article in the road map. It lays the foundation for the concepts that you will learn more about later. Each of the other articles expands on one of those concepts.
Properties¶
Kivy introduce a new way of declaring the properties within a class. Before:
class MyClass(object):
def __init__(self):
super(MyClass, self).__init__()
self.numeric_var = 1
After, using Kivy’s properties:
class MyClass(EventDispatcher):
numeric_var = NumericProperty(1)
Theses properties implement the Observer pattern. You can:
- Allow manipulating your widgets in kv language more easily
- Automatically observe any changes and dispatch functions/code accordingly
- Check and validate values
- Optimize memory management
To use them, you have to declare them at class level. That is, directly in the class, not in any method of the class. A property is a class attribute that will automatically create instance attributes. Each property by default provides an on_<propertyname> event that is called whenever the property’s state/value changes .
- Kivy provides the following properties:
- NumericProperty, StringProperty, ListProperty, ObjectProperty, BooleanProperty, BoundedNumericProperty, OptionProperty, ReferenceListProperty, AliasProperty, DictProperty,
For an in-depth explaination, look at Properties
Kv Design Language¶
Kivy provides a design language specifically geared towards ease of GUI Design, which makes it easier to separate interface design and logic from internal design and logic. For example:

In the above code :
<LoginScreen>: # every class in your app can be represented by a rule like this in the kv file
GridLayout: # this is how you add your widget/layout to the parent (note the indentation).
rows: 2 # this how you set each property of your widget/layout
That’s it, that’s how simple it is to design your GUI in the kv language. To get a more in-depth understanding look at Introduction to the Kivy Language
Events¶
Kivy is mostly event-based, that’s mean the flow of the program is determined by events.
Clock events

The Clock object allows you to schedule a function call in the future, as a one-time event with schedule_once(), or as a repetitive event with schedule_interval().
You can also create Triggered events with create_trigger(), multiple call to a trigger will schedule a function call only once.
Input events

All the mouses click, touchs, scroll wheel are part of the MotionEvent, extended by Input Postprocessing, dispatched through the on_motion in Window, then in the on_touch_down(), on_touch_move(), on_touch_up() in Widget
For an in-depth explaination, have a look at Input management.
Class events

Our base class EventDispatcher, used by Widget, use the power of ours Properties for dispatching changes. IE, when a widget changes its position or size, an event is fired.
In addition, you have the possibility to create your own event using register_event_type(), as the on_press/on_release in Button.
Another thing to note is that if you override an event, you become responsible for implementing all its behaviour previously handled by the base class. The easiest way to do this is to call super():
def on_touch_down(self, touch):
if super(OurClassName, self).on_touch_down(touch):
return True
if not self.collide_point(touch.x, touch.y):
return False
print 'you touched me!'
return True
Get more familiar with events by reading the Events documentation.
Non-widget stuff¶
Animation is used to change a Widget’s properties (size/pos/center...), to a target value, in a target time. Various transition functions are provided. Using them, you can animate widgets and build very smooth UI behaviours. | ![]() |
Atlas is a class for managing texture maps, i.e. packing multiple textures into one image. Using it allows you to reduce the number of images to load and speed up the application start. | ![]() |
Clock provides you with a convenient way to do jobs at set time intervals and is preferred over sleep() which would block the kivy Event Loop. These intervals can be set relative to the OpenGL Drawing instructions, before or after frame. Clock also provides you with a way to create triggered events that are grouped together and only called once before the next frame. | |
UrlRequest is useful to do asynchronous requests without blocking the event loop, and manage the result and progress with callbacks. |
Layouts¶
Layouts are used to arrange widgets in a perticular manner:
AnchorLayout: widgets can be anchored to 'top', 'bottom', 'left', 'right', 'center'
BoxLayout: widgets are arranged in a box in either 'vertical' or 'horizontal' orientation
FloatLayout: Widgets are essentially unrestricted
RelativeLayout: Child widgets are positioned relative to the layout.
GridLayout: widgets are arranged in a grid defined by `rows` and `cols` properties
StackLayout: widgets are stacked in `lr-tb` (left to right then top to bottom) or `tb-lr` order
Size_hint: defines the size of a widget in parent space as a percentage. Values are restricted to the range 0.0 - 1.0 i.e. 0.01 = 1% and 1. = 100%. pos_hint: is used to place the widget relative to the parent.
size_hint and pos_hint are used to calculate widget’s size and position only if the value/s are not set to None. However one can set these to None and provide direct values in screen coordinates.
For a detailed look at how you can arrange widgets using layouts look in AnchorLayout BoxLayout FloatLayout GridLayout StackLayout RelativeLayout
Drawing¶
Each widget has a canvas, i.e. a place to draw on. The canvas is a group of instructions that should be executed whenever there is a change to the widget’s graphics representation. You can add two types of instructions to the canvas, context instructions and vertex instructions. You can add instructions either from Python or from kv (the preferred way). If you add them from kv, the advantage is that they are automatically updated when any property they depend on changes. In Python, you need to do this yourself.

In both cases the canvas of the MyWidget is re-drawn whenever the position or the size of the widget changes.
You can use canvas.before or canvas.after . This allows you to separate your instructions based on when you want them to happen.
For an in-depth look at how Kivy’s graphics are handled, look here.
Packaging¶
Examples¶
Directory | Filename/s | Example Description |
---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Diving in¶
To further get into kivy take a look at Welcome to Kivy
Kivy comes with a set of Examples in the kivy_installation/examples directory. You should try modifying/improving/adapting them to your needs.
Browse the snippet wiki . You can even add your snippet in the user snippets section.
Understand the basics about kivy graphics
Take a look at the built-in widgets
Follow the Programming Guide to get even more familiar with kivy.
See how to use different Modules like the Inspector for live inspection in the modules section.
Learn how to handle custom Input
See how kivy has been extended with extensions support.
Familiarize yourself with the kivy framework
Kivy is open source so you can contribute , take a look at Contributing section to see the guidelines.