Getting Started¶
Introduction¶
Creating Kivy apps is fun and enriching. This guide should be the perfect starting point to get you on the right track for app development.

On your computer, you can create apps that run on:
- Desktop computer: MacOSX, Linux, Windows.
- iOs Devices: iPad, iPhone
- Android devices: Tablets, Phones.
- And any others touch enabled professional/homebrew devices supporting TUIO.
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 best practices, as this is an introduction, pointers will be provided at the end of each section to find more information.
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 will know where to look for informations for the more challenging stuff your innovative applications will require.
Enough with the introductions, let’s get down to business.
Installation¶
Using Kivy, you can use your favorite development environment to start coding your App.
To get started, you need to download the latest version of Kivy:
Please refer to the installation instructions for your specific platform:



Development Version
If you want to use 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 Development Version
A first App¶
Immerse yourself into the world of Kivy with your first App.

The Pong Game Tutorial introduces the fundamental design patterns and application development process. As you follow the tutorial, you will create a simple app. You will also learn how to run your app in on your OS. The simple steps in the tutorial introduce elegant, useful concepts that you use over and over again in app development.
Your 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.
Kivy Properties¶
Kivy properties are an implementation of the observer pattern . Kivy’s properties are useful to:
- Allow manipulating your widgets in kv language more easily
- Automatically observe any changes and dispatch functions/code accordingly
- Value checking/validation
- Optimize memory managment
To use them, you have to declare them at class level. That is, directly in the class, not în any method of the class, the property is a class attribute that will automatically create instance attributes. Each property by default provides a on_property event that is called whenever the properties state/value changes .
- Kivy provides the following properties:
- NumericProperty, StringProperty, ListProperty, ObjectProperty, BooleanProperty, BoundedNumericProperty, OptionProperty, ReferenceListProperty, AliasProperty, DictProperty,
For a in-depth look in how-to use kivy properties start here
Kv Design Language¶
Kivy provides a design language specifically geared towards ease of GUI Design, it makes seperating the interface design and logic from the internal design and logic easier. 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 kv language. To get a more in-depth understanding look at Introduction to the Kivy Language
Events¶
Kivy is event oriented. The most basic events you will work with are.
1. Clock events:
- Repetitive events : X times per second using schedule_interval()
- One-time event : schedule_once
- Trigger events: called only once for the next frame
2. Widget events :
- Property events: if your widget changes its position or size, an event is fired
- Widget defined events: A Widget can define custom events
Eg. on_press() and on_release() events in Button Widget
3. Input events:
- Touch events: There are three of them:
- on_touch_down: which is dispatched at the begining of a touch
- on_touch_move: which is dispatched every time a touch is moving
- on_touch_up: which is dispatched when the end of the touch
Note** that, all widgets get all of these events whatever there positions,
allowing for the widgets to react to any event.
- Keyboard events
- system kayboard events (hard/soft keyboards)
- virtual Keyboard events (kivy provided virtual keyboard)
Another thing to Note is that if you override an event, you now become responsible of implementing all it’s behavoiur handled by the base class, the easiest way to do that is to call super
def on_touch_down(self, touch):
if super(OurClaseName, self).on_touch_down(touch):
return True
if not self.collide_point(touch.x, touch.y):
return False
print 'you touched me!'
Get more familiar with events by reading the following event documentation.
Non widgets 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 smoth UI behaviours. | ![]() |
Atlas is a class for managing texture maps, i.e. packing multiple texture into one image. Using it allow to reduce the number of images to load and speedup the application starting. | ![]() |
Clock provides you with a convenient way to do jobs at set time intervals and is preffered over sleep() as sleep would block 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 clubbed togeather 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 arranged in a box either in 'vertical' or 'horizontal' orientation
FloatLayout: Widgets are essentially unrestricted
GridLayout: widgets 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`
Size_hint: defines the size of a widget in parent space in percentages, values restricted to range 0 - 1 i.e. 0.01 = 1% and 1. = 100%. pos_hint: is used to place the widget relative to the parent.
size_hint or 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
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 put instructions either from python or from kv (preffered 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 seperate your instructions based on when you want each to happen.
For an in depth look at how Kivys Graphics are handled, look here
Packaging¶
Packaging your application¶
Diving in¶
To further get into kivy take a look at Welcome to Kivy
Kivy comes with a set of Examples in the 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 programing 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 kivy framework
Kivy is open source so you can contribute , take a look at Contributing section to follow the guidelines.