Skillversitas

Installation and Setup

Kivy installs as a single pip package, and on a modern machine that is the whole setup: pip install kivy brings the library, its rendering backends, and the windowing glue. The practical concerns are the platform specifics - Linux needs a few system libraries for the window backend, and the first run should be the canonical smoke test that proves the render loop, the event loop, and a widget all work. This chapter covers the install, the platform notes, and a verification app you can run in under a minute.

Install

# the standard install
pip install kivy

# verify the version
python -c "import kivy; print(kivy.__version__)"

# for Android/iOS development, the build tool:
pip install kivy[dev]      # or use the kivy-android / kivy-ios scripts

The kivy package pulls the platform dependencies it needs (the SDL2-based windowing, the OpenGL rendering context). On Windows and macOS the wheel is self-contained. On Linux, the window backend needs the SDL2 and OpenGL system libraries - on a typical distro that is libsdl2-2.0-0 and libgl1 (plus libgl1-mesa-glx on some), and a missing one shows up as an import or window-creation error naming the shared object. The python -c "import kivy" check catches the import-time failures; the smoke test below catches the window-time ones.

The Smoke Test

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

Builder.load_string("""
BlinkButton:
    text: "Kivy works"
    size_hint: (0.5, 0.5)
    pos_hint: {'center': (0.5, 0.5)}
""")

class BlinkButton(Button):
    pass

class SmokeApp(App):
    def build(self):
        return BlinkButton()

if __name__ == "__main__":
    SmokeApp().run()

Run it with python main.py: a window opens with a button in the center. That one screen exercises the three systems at once - the window backend created the window, the render loop drew the button, and the event loop is running (close the window and the process exits cleanly). If the window appears, the installation is honest. If it fails, the error message points at the layer: a missing shared library is a system dependency, a blank window is a GPU/driver issue (try the KIVY_GL_BACKEND or software rendering env vars), and an import error is a package problem.

Project Shape

myapp/
  main.py          # the App subclass and entry point
  myapp.kv         # the UI, loaded by name from main.py
  data/            # images, fonts, bundled assets
    icon.png

The convention this tutorial uses: one main.py with the App subclass, and a .kv file whose name matches the module (main.py loads main.kv automatically - Kivy looks for a KV file next to the Python file). For a real app, put the UI in the .kv, the behavior in the Python, and assets under data/. The automatic KV loading is a convenience that matters: if the file is not named after the module, you must load it explicitly, which is the first "why is my UI not showing" cause in a new project.

Environment Variables Worth Knowing

  • KIVY_NO_CONSOLELOG - quiet the console log (the window's own log is unaffected).
  • KIVY_WINDOW_WIDTH / KIVY_WINDOW_HEIGHT - override the window size for testing different frames.
  • KIVY_GL_BACKEND - select the OpenGL backend when a driver misbehaves (the software fallback for headless CI).
  • KIVY_IMAGE / KIVY_TEXT - force a specific provider when the default fails on an unusual image or font.

These are the dials that turn a "works on my machine" report into a diagnosis: most environment-specific Kivy failures are solved by one of these variables rather than a code change. For CI and headless testing, the combination of the software GL backend and a short auto-quit timer is the standard pattern - the app starts, renders one frame, and exits, which is enough to catch a broken build without a display.

Summary

Install with pip install kivy, verify the version with import kivy, and run the smoke test - a one-button app that proves the window, the render loop, and the event loop together. On Linux, expect to install the SDL2 and OpenGL system libraries when the window fails to open; the error names the missing object. Keep the project shape simple - a main.py App subclass plus a same-named .kv that Kivy auto-loads, assets under data/ - and know the environment variables (KIVY_WINDOW_WIDTH, KIVY_GL_BACKEND, the log switches) that solve the platform-specific failures. With a window on screen, the next chapter turns that skeleton into the actual first app.