Kivy

2.3.1 · active · verified Thu Apr 16

Kivy is an open-source Python framework for developing GUI applications that run cross-platform, including desktop (Windows, macOS, Linux), mobile (Android, iOS), and embedded platforms. It facilitates rapid prototyping and easy interaction design, supporting multi-touch applications with a reusable codebase. Kivy is released under the MIT License, actively developed by a strong community, and is currently at version 2.3.1.

Common errors

```
ModuleNotFoundError: No module named 'kivy'
```
cause Kivy is not installed in the currently active Python environment, or the Python interpreter running the script is not the one where Kivy was installed.

fix Activate your virtual environment (if using one) and reinstall Kivy using `pip install "kivy[full]"`. Verify the Python interpreter being used by your IDE or terminal.
```
ImportError: DLL load failed: The specified module could not be found. (on Windows) or similar SDL2/OpenGL related errors.
```
cause The necessary binary dependencies for Kivy's graphical backend (like SDL2, Glew, or GStreamer) are missing or incorrectly installed, especially on Windows.

fix Install Kivy with the `full` extra: `pip install "kivy[full]"`. If the problem persists, ensure your system has up-to-date graphics drivers and consider installing Visual C++ Build Tools on Windows for source compilation.
```
kivy.lang.BuilderException: Invalid indentation or syntax errors in .kv file.
```
cause The Kivy Language (.kv files) is sensitive to indentation (4 spaces recommended) and specific syntax rules. Improper formatting or typos can lead to this error.

fix Carefully review your .kv file for correct indentation, proper use of `app`, `root`, and `self` keywords, and adherence to Kv language syntax. Ensure no mixed tabs and spaces.

Warnings

breaking Kivy 2.0.0 dropped support for Python 2.7. All Kivy 2.x.x versions require Python 3.x.
Fix: Ensure you are using Python 3.6 or newer. For Kivy 2.3.1, Python 3.8-3.13 are supported.
breaking Kivy 2.3.0 and newer removed support for Python 3.7 and Windows 32-bit environments.
Fix: Upgrade your Python installation to 3.8 or newer (3.8-3.13 for Kivy 2.3.1) and ensure you are using a 64-bit operating system if on Windows.
deprecated Several core provider properties and methods, such as `status` and `filename` in audio providers, and `toggle_fullscreen` in the window provider, were deprecated in Kivy 2.3.0.
Fix: Refer to the Kivy 2.3.0 changelog for specific replacements and updated APIs. These deprecated features will be removed entirely in Kivy 3.0.0.
gotcha Installing Kivy without its binary dependencies (e.g., SDL2, GStreamer) might lead to issues with window creation, input, or multimedia playback. While `pip install kivy` works for the core library, graphical applications often require these backends.
Fix: Use `pip install "kivy[full]"` to include common binary dependencies for most platforms, or install specific `kivy-deps` packages manually. Ensure you're in an activated virtual environment.
breaking Kivy 3.0.0, the next major release, is expected to remove all features deprecated in the 1.x.x and 2.x.x series. Prepare for significant API changes.
Fix: Actively monitor the Kivy project's announcements and changelogs for Kivy 3.0.0 to identify and migrate away from any deprecated features in your codebase.

Install

pip install kivy Basic Kivy installation
pip install "kivy[full]" Kivy with common dependencies (SDL2, GStreamer, Glew)
python -m venv kivy_venv && source kivy_venv/bin/activate # On Windows: kivy_venv\Scripts\activate pip install "kivy[full]" Recommended: Install in a virtual environment with full dependencies

Imports

App
wrong:
```
import App
```
correct:
```
from kivy.app import App
```
The `App` class is the base for Kivy applications and must be imported from `kivy.app`.
Label
wrong:
```
from kivy.label import Label
```
correct:
```
from kivy.uix.label import Label
```
UIX (User Interface eXtensions) module contains Kivy's widgets, including `Label`.

Quickstart

This minimal Kivy application creates a simple window displaying 'Hello, Kivy!'. It defines an `App` subclass, overrides the `build` method to return a `Label` widget, and then runs the application instance. The `kivy.require()` call is a good practice to ensure compatibility with your current Kivy version.

import kivy
kivy.require('2.3.1') # specify the Kivy version you're using

from kivy.app import App
from kivy.uix.label import Label

class MyApp(App):
    def build(self):
        return Label(text='Hello, Kivy!')

if __name__ == '__main__':
    MyApp().run()

view raw JSON →