Installing Kivy — Kivy 2.3.0 documentation (2024)

Installation for Kivy version 2.3.0. Read the changelog here.For other Kivy versions, select the documentation from the dropdown on the top left.

Kivy 2.3.0 officially supports Python versions 3.7 - 3.12.

Platform	Installation	Packaging
Windows	pip	PyInstaller
macOS	pip, Kivy.app	Kivy.app, PyInstaller
Linux	pip, PPA	—
*BSD (FreeBSD,..)	pip	—
RPi	pip	—
Android	python-for-android	python-for-android
iOS	kivy-ios	kivy-ios
Anaconda	conda	—

Using pip¶

The easiest way to install Kivy is with pip, which installs Kivy using either apre-compiled wheel, if available, otherwise from source (see below).

Kivy provides pre-compiled wheels for the supported Pythonversions on Windows, macOS, Linux, and RPi.

If no wheels are available pip will build the package from sources (i.e. on *BSD).

Alternatively, installing from source is required for newer Python versions not listedabove or if the wheels do not work or fail to run properly.

On RPi, when using a 32 bit OS, wheels are provided for Python 3.7 (Raspberry Pi OS Buster), Python 3.9 (Raspberry Pi OS Bullseye)and Python 3.11 (Raspberry Pi OS Bookworm) via the PiWheels project.

For other Python versions, on 32 bit OSes, you will need to install from source.

Setup terminal and pip¶

Before Kivy can be installed, Python and pip needs to be pre-installed.Then, start a new terminal that hasPython available. In the terminal, update pip and other installationdependencies so you have the latest version as follows (for linux users you may have tosubstitute python3 instead of python and also add a --user flag in thesubsequent commands outside the virtual environment):

python -m pip install --upgrade pip setuptools virtualenv

Create virtual environment¶

Create a new virtual environmentfor your Kivy project. A virtual environment will prevent possible installation conflictswith other Python versions and packages. It’s optional but strongly recommended:

Create the virtual environment named kivy_venv in your current directory:
```
python -m venv kivy_venv
```
Activate the virtual environment. You will have to do this step from the current directoryevery time you start a new terminal. This sets up the environment so the new kivy_venvPython is used.
For Windows default CMD, in the command line do:
```
kivy_venv\Scripts\activate
```
If you are in a bash terminal on Windows, instead do:
```
source kivy_venv/Scripts/activate
```
If you are in linux or macOS, instead do:
```
source kivy_venv/bin/activate
```

Your terminal should now preface the path with something like (kivy_venv), indicating thatthe kivy_venv environment is active. If it doesn’t say that, the virtual environmentis not active and the following won’t work.

Install Kivy¶

Finally, install Kivy using one of the following options:

Pre-compiled wheels¶

The simplest is to install the current stable version of kivy and optionally kivy_examplesfrom the kivy-team provided PyPi wheels. Simply do:

python -m pip install "kivy[base]" kivy_examples

This also installs the minimum dependencies of Kivy. To additionally install Kivy withaudio/video support, install either kivy[base,media] or kivy[full].See Kivy’s dependencies for the list of selectors.

Note

The Pillow library is a dependency of both kivy[base] and kivy[full].

For Windows 32-bit users, please note that the latest releases of Pillow arenot available as binary distributions on PyPI. However, Kivy also supports Pillow==9.5.0,which have a binary distribution for all supported Python versions, even on Windows 32-bit.

If you are on Windows 32-bit and prefer not to build Pillow from source,you can use the --only-binary Pillow flag with the following command to instruct pipto install the binary distribution of Pillow, albeit not the latest version:

python -m pip install --only-binary Pillow "kivy[base]"

Note

When using Raspberry Pi OS Lite or similar Linux-based headless systems, it may be necessary to install additionaldependencies to ensure Kivy functions properly.

For instance, on Raspberry Pi OS Lite, you will be required to install the following dependencies:

apt-get install libgl1-mesa-glx libgles2-mesa libegl1-mesa libmtdev1

From source¶

If a wheel is not available or is not working, Kivy can be installed from sourcewith some additional steps. Installing from source means that Kivy will be installedfrom source code and compiled directly on your system.

Pre-release, pre-compiled wheels¶

To install a pre-compiled wheel of the last pre-release version of Kivy, instead of thecurrent stable version, add the --pre flag to pip:

python -m pip install --pre "kivy[base]" kivy_examples

This will only install a development version of Kivy if one was released toPyPi. Instead, one can also install thelatest cutting-edge Nightly wheels from the Kivy server with:

python -m pip install kivy --pre --no-deps --index-url https://kivy.org/downloads/simple/python -m pip install "kivy[base]" --pre --extra-index-url https://kivy.org/downloads/simple/

It is done in two steps, because otherwise pip may ignore the wheels on the server and installan older pre-release version from PyPi.

Development install¶

Note

We suggest to select master or relevant branch/version of doc from top left,ensuring correct version/branch of kivy git repository you are working with.

If you want to edit Kivy before installing it, or if you want to try fixing some Kivy issueand submit a pull request with the fix, you will need to first download the Kivy source code.The following steps assumes git is pre-installed and available in the terminal.

The typical process is to clone Kivy locally with:

git clone https://github.com/kivy/kivy.git

This creates a kivy named folder in your current path. Next, follow the same steps of theInstalling from source above, but instead of installing Kivy via adistribution package or zip file, install it as aneditable install.

In order to do so, first change into the Kivy folder you just cloned::and then install Kivy as an editable install:

cd kivypython -m pip install -e ".[dev,full]"

Now, you can use git to change branches, edit the code and submit a PR.Remember to compile Kivy each time you change cython files as follows:

python setup.py build_ext --inplace

Or if using bash or on Linux, simply do:

make

to recompile.

To run the test suite, simply run:

pytest kivy/tests

or in bash or Linux:

make test

On *BSD Unix remember to use gmake (GNU) in place of make (BSD).

Checking the demo¶

Kivy should now be installed. You should be able to import kivy in Python or,if you installed the Kivy examples, run the demo.

on Windows:

python kivy_venv\share\kivy-examples\demo\showcase\main.py

in bash, Linux and macOS:

python kivy_venv/share/kivy-examples/demo/showcase/main.py

on *BSD Unix:

python3 kivy_venv/share/kivy-examples/demo/showcase/main.py

The exact path to the Kivy examples directory is also stored in kivy.kivy_examples_dir.

The 3d monkey demo under kivy-examples/3Drendering/main.py is also fun to see.

Installation using Conda¶

If you use Anaconda, you caninstall Kivy with its package manager Conda using:

conda install kivy -c conda-forge

Do not use pip to install kivy if you’re using Anaconda, unless you’re installing from source.

Installing Kivy’s dependencies¶

Kivy supports one or more backends for its core providers. E.g. it supports glew, angle,and sdl2 for the graphics backend on Windows. For each category (window, graphics, video,audio, etc.), at least one backend must be installed to be able to use the category.

To facilitate easy installation, we provide extras_requiregroupsthat will install selected backends to ensure a working Kivy installation. So one can installKivy more simply with e.g.``pip install “kivy[base,media,tuio]”``. The full list of selectors andthe packages they install is listed insetup.py. The exact packages in each selectormay change in the future, but the overall goal of each selector will remain as described below.

We offer the following selectors:

base: The minimum typical dependencies required for Kivy to run,
not including video/audio.
media: Only the video/audio dependencies required for Kivy to
be able to play media.
full: All the typical dependencies required for Kivy to run, including video/audio and
most optional dependencies.
dev: All the additional dependencies required to run Kivy in development mode
(i.e. it doesn’t include the base/media/full dependencies). E.g. any headers required forcompilation, and all dependencies required to run the tests and creating the docs.
tuio: The dependencies required to make TUIO work (primarily oscpy).

The following selectors install backends packaged as wheels by kivy under the Kivy_deps namespace.They are typically released and versioned to match specific Kivy versions, so we provide selectorsto facilitate installation (i.e. instead of having to do pip install kivy kivy_deps.sdl2==x.y.z,you can now do pip install "kivy[sdl2]" to automatically install the correct sdl2 for the Kivyversion).

gstreamer: The gstreamer video/audio backend, if it’s available
(currently only on Windows)
angle: A alternate OpenGL backend, if it’s available
(currently only on Windows)
sdl2: The window/image/audio backend, if it’s available (currently only on Windows,
on macOS, Linux and *BSD Unix is already included in the main Kivy wheel).
glew: A alternate OpenGL backend, if it’s available (currently only on Windows)

Following are the kivy_deps dependency wheels:

gstreamer (optional)
kivy_deps.gstreamer is an optional dependency which is only needed for audio/video support.We only provide it on Windows, for other platforms it must be installed independently.Alternatively, use ffpyplayer instead.
glew and/orangle
kivy_deps.glew and kivy_deps.angle are for OpenGL.You can install both, that is no problem. It is only available on Windows. On otherplatforms it is not required externally.
One can select which of these to use for OpenGL using theKIVY_GL_BACKEND environment variable: By setting it to glew(the default), angle_sdl2, or sdl2. Here, angle_sdl2 is a substitute forglew but requires kivy_deps.sdl2 to be installed as well.
sdl2
kivy_deps.sdl2 is for window/images/audio and optionally OpenGL. It is only available on Windowsand is included in the main Kivy wheel for other platforms.

Python glossary¶

Here we explain how to install Python packages, how to use the command line and what wheels are.

Installing Python¶

Kivy is written inPythonand as such, to use Kivy, you need an existinginstallation of Python.Multiple versions of Python can be installed side by side, but Kivy needs tobe installed as package under each Python version that you want to use Kivy in.

To install Python, see the instructions for each platform:Windows, macOS,Linux, RPi,*BSD.

Once Python is installed, open the console and make surePython is available by typing python --version.

How to use the command line¶

To execute any of the pip or wheel commands given here, you need a command line (here also called console, terminal, shell or bash, where the last two refer to Linux / *BSD Unix style command lines) and Python must be on the PATH.

The default command line on Windows is thecommand prompt, short cmd. Thequickest way to open it is to press Win+R on your keyboard.In the window that opens, type cmd and then press enter.

Alternative Linux style command lines on Windows that we recommend areGit for Windows or Mysys.

Note, the default Windows command line can still be used, even if a bash terminal is installed.

To temporarily add your Python installation to the PATH, simply open your command line and then use the cd command to change the current directory to where python is installed, e.g. cd C:\Python37.

If you have installed Python using the default options, then the path to Python will already be permanently on your PATH variable. There is an option in the installer which lets you do that, and it is enabled by default.

If however Python is not on your PATH, follow the these instructions to add it:

Instructions for the windows command line
Instructions for bash command lines

What is pip and what are wheels¶

In Python, packages such as Kivy can be installed with the python packagemanager, named pip (“python install package”).

When installing from source, some packages, such as Kivy, require additional steps, like compilation.

Contrary, wheels (files with a .whl extension) are pre-builtdistributions of a package that has already been compiled.These wheels do not require additional steps when installing them.

When a wheel is available on pypi.org (“Python Package Index”) it can be installed with pip. For example when you execute python -m pip install kivy in a command line, this will automatically find the appropriate wheel on PyPI.

When downloading and installing a wheel directly, use the commandpython -m pip install <wheel_file_name>, for example:

python -m pip install C:\Kivy-1.9.1.dev-cp27-none-win_amd64.whl

What are nightly wheels¶

Every day we create a snapshot wheel of the current development version of Kivy (‘nightly wheel’).You can find the development version in the master branch of theKivy Github repository.

As opposed to the last stable release (which we discussed in the previous section), nightlywheels contain all the latest changes to Kivy, including experimental fixes.For installation instructions, see Pre-release, pre-compiled wheels.

Warning

Using the latest development version can be risky and you might encounterissues during development. If you encounter any bugs, please report them.