Installation on Windows¶

Beginning with 1.9.1 we provide binary wheels for Kivy and all its dependencies to be used with an existing Python installation. See Installation .

We also provide nightly wheels generated using Kivy master. See Nightly wheel installation . See also Upgrading from a previous Kivy dist . If installing kivy to an alternate location and not to site-packages, please see Installing Kivy to an alternate location .

Installation¶

Now that python is installed, open the Command line and make sure python is available by typing python —version . Then, do the following to install.

Ensure you have the latest pip and wheel:

Install the dependencies (skip gstreamer (

If you encounter a MemoryError while installing, add after pip install an option –no-cache-dir .

For Python 3.5+, you can also use the angle backend instead of glew. This can be installed with:

(Optionally) Install the kivy examples:

The examples are installed in the share directory under the root directory where python is installed.

That’s it. You should now be able to import kivy in python or run a basic example if you installed the kivy examples:

If you encounter any permission denied errors, try opening the Command prompt as administrator and trying again.

What are wheels, pip and wheel¶

In Python, packages such as Kivy can be installed with the python package manager, pip. Some packages such as Kivy require additional steps, such as compilation, when installing using the Kivy source code with pip. Wheels (with a .whl extension) are pre-built distributions of a package that has already been compiled and do not require additional steps to install.

When hosted on pypi one installs a wheel using pip , e.g. python -m pip install kivy . When downloading and installing a wheel directly, python -m pip install wheel_file_name is used, such as:

Nightly wheel installation¶

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

Snapshot wheels of current Kivy master are created on every commit to the master branch of kivy repository. They can be found here. To use them, instead of doing python -m pip install kivy we’ll install one of these wheels as follows.

• Python 2.7, 32bit
• Python 3.4, 32bit
• Python 3.5, 32bit
• Python 3.6, 32bit

• Python 2.7, 64bit
• Python 3.4, 64bit
• Python 3.5, 64bit
• Python 3.6, 64bit

1. Perform steps 1 and 2 of the above Installation section.
2. Download the appropriate wheel for your system.
3. Install it with python -m pip install wheel-name where wheel-name is the name of the renamed file and add deps to the PATH .

Kivy examples are separated from the core because of their size. The examples can be installed separately on both Python 2 and 3 with this single wheel:

Kivy’s dependencies¶

We offer wheels for Kivy and its dependencies separately so only desired dependencies need be installed. The dependencies are offered as optional sub-packages of kivy.deps, e.g. kivy.deps.sdl2 .

Currently on Windows, we provide the following dependency wheels:

• gstreamer for audio and video
• glew and/or angle (3.5 only) for OpenGL
• sdl2 for control and/or OpenGL.

One can select which of these to use for OpenGL use using the KIVY_GL_BACKEND envrionment variable by setting it to glew (the default), angle , or sdl2 . angle is currently in an experimental phase as a substitute for glew on Python 3.5 only.

gstreamer is an optional dependency which only needs to be installed if video display or audio is desired. ffpyplayer is an alternate dependency for audio or video.

Command line¶

Know your command line. To execute any of the pip or wheel commands, one needs a command line tool with python on the path. The default command line on Windows is Command Prompt, and the quickest way to open it is to press Win+R on your keyboard, type cmd in the window that opens, and then press enter.

Alternate linux style command shells that we recommend is Git for Windows which offers a bash command line as well as git. Note, CMD can still be used even if bash is installed.

Walking the path! To add your python 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:\Python27 . Alternatively if you only have one python version installed, permanently add the python directory to the path for cmd or bash.

Use development Kivy¶

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

To compile and install kivy using the kivy source code or to use kivy with git rather than a wheel there are some additional steps:

Both the python and the Python\Scripts directories must be on the path. They must be on the path every time you recompile kivy.

Ensure you have the latest pip and wheel with:

Get the compiler. For Python python\Lib\distutils\distutils.cfg file and add the two lines:

Install MinGW with:

For Python 3.5 we use the MSVC compiler. For 3.5, Visual Studio 2015 is required, which is availible for free. Just download and install it and you’ll be good to go.

Visual Studio is very big so you can also use the smaller, Visual C Build Tools instead.

Set the environment variables. On windows do:

These variables must be set everytime you recompile kivy.

Install the other dependencies as well as their dev versions (you can skip gstreamer and gstreamer_dev if you aren’t going to use video/audio):

If you downloaded or cloned kivy to an alternate location and don’t want to install it to site-packages read the next section.

Finally compile and install kivy with pip install filename , where filename can be a url such as https://github.com/kivy/kivy/archive/master.zip for kivy master, or the full path to a local copy of a kivy.

Compile Kivy¶

Start installation of Kivy cloned from GitHub:

If the compilation succeeds without any error, Kivy should be good to go. You can test it with running a basic example:

Installing Kivy to an alternate location¶

In development Kivy is often installed to an alternate location and then installed with:

That allows Kivy to remain in its original location while being available to python, which is useful for tracking changes you make in Kivy for example directly with Git.

To achieve using Kivy in an alternate location extra tweaking is required. Due to this issue wheel and pip install the dependency wheels to python\Lib\site-packages\kivy . So they need to be moved to your actual kivy installation from site-packages.

After installing the kivy dependencies and downloading or cloning kivy to your favorite location, do the following:

1. Move the contents of python\Lib\site-packages\kivy\deps to your-path\kivy\deps where your-path is the path where your kivy is located. That means if you cloned from GitHub, the deps have to end up in the inner kivy folder.
2. Remove the python\Lib\site-packages\kivy directory altogether.
3. From python\Lib\site-packages move all kivy.deps.*.dist-info directories to your-path right next to kivy .

Now you can safely compile kivy in its current location with one of these commands:

If kivy fails to be imported, you probably didn’t delete all the *.dist-info folders and and the kivy or kivy.deps* folders from site-packages.

Making Python available anywhere¶

There are two methods for launching python on your *.py files.

Double-click method¶

If you only have one Python installed, you can associate all *.py files with your python, if it isn’t already, and then run it by double clicking. Or you can only do it once if you want to be able to choose each time:

1. Right click on the Python file (.py file extension) of the application you want to launch
2. From the context menu that appears, select Open With
3. Browse your hard disk drive and find the file python.exe that you want to use. Select it.
4. Select “Always open the file with…” if you don’t want to repeat this procedure every time you double click a .py file.
5. You are done. Open the file.

Send-to method¶

You can launch a .py file with our Python using the Send-to menu:

1. Browse to the python.exe file you want to use. Right click on it and copy it.
2. Open Windows explorer (File explorer in Windows 8), and to go the address ‘shell:sendto’. You should get the special Windows directory SendTo
3. Paste the previously copied python.exe file as a shortcut.
4. Rename it to python

You can now execute your application by right clicking on the .py file -> “Send To” -> “python

Upgrading from a previous Kivy dist¶

To install the new wheels to a previous Kivy distribution all the files and folders, except for the python folder should be deleted from the distribution. This python folder will then be treated as a normal system installed python and all the steps described in Installation can then be continued.

kivy Installation & Setup

Example

Windows

There are two options how to install Kivy:

First ensure python tools are up-to-date.

Then install the basic dependencies.

Although Kivy already has providers for audio & video, GStreamer is required for more advanced stuff.

To make it simpler,

in the following text means a path to the directory with python.exe file.

The wheel package provides compiled Kivy, but with removed cython source components, which means the core code can’t be recompiled using this way. Python code, however, is editable.

The stable version of Kivy is available on pypi.

The latest version from the official repository is available through nightly-built wheels available on google drive. Visit the link in docs matching your python version. After a proper wheel is downloaded, rename it to match the formatting of this example and run the command.

There are more required dependencies needed to install Kivy from source than using the wheels, but the installation is more flexible.

Create a new file in

\Lib\distutils\distutils.cfg with these lines to ensure a proper compiler will be used for the source code.

Then the compiler is needed. Either use some you already have installed, or download mingwpy . The important files such as gcc.exe will be located in

Don’t forget to set environment variables to let Kivy know what providers it should use.

Now install the additional dependencies required for the compilation.

Check Paths section to ensure everything is set properly and install Kivy. Choose one of these options:

Paths

Kivy needs an access to the binaries from some dependencies. This means the correct folders have to be on the environment’s PATH variable.

This way Python IDLE IDE can be included to the path with

\Lib\idlelib; . Then write idle into console and IDLE will be ready to use Kivy.

Simplify it

To avoid repetitive setting of environment variables either set each necessary path this way or make a batch( .bat ) file with these lines placed into

To run Kivy project after installation run cmd.exe or the batch file and use python .py

installation on Ubuntu

For install kivy on ubuntu with kivy example open terminal and run following command

Installation on Windows¶

Using Conda¶

If you use Anaconda, you can simply install kivy using:

Otherwise, continue below to install Kivy in a native Python installation.

Prerequisites¶

Kivy is written in Python and as such, to use Kivy, you need an existing installation of Python. Multiple versions of Python can be installed side by side, but Kivy needs to be installed in each Python version that you want to use Kivy in.

Beginning with 1.9.1 we provide binary wheels for Kivy and all its dependencies to be used with an existing Python installation. See Installing the kivy stable release .

We also provide nightly wheels generated using Kivy master. See Nightly wheel installation . If installing kivy to an alternate location and not to site-packages, please see Installing Kivy and editing it in place .

Updating Kivy from a previous release¶

When updating from a previous Kivy release, all the Kivy dependencies must be updated first. Typically, just adding –upgrade to the pip install … commands below is sufficient for pip to update them.

When updating from Kivy 1.10.1 or lower to 1.11.0 or higher, one must manually uninstall all kivy dependencies before upgrading because won’t update them properly. This is done with:

assuming all the dependencies were previously installed. See Kivy’s dependencies for more details.

After uninstalling, continue with the installation below.

Installing the kivy stable release¶

Kivy 1.11.0 is the last release that supports Python 2.

Now that python is installed, open the Command line and make sure python is available by typing python —version . Then, do the following to create a new virtual environment (optionally) and install the most recent stable kivy release ( 1.11.0 ) and its dependencies.

Ensure you have the latest pip, wheel, and virtualenv:

Optionally create a new virtual environment for your Kivy project. Highly recommended:

First create the environment named kivy_venv in your current directory:

Activate the virtual environment. You’ll have to do this step from the current directory every time you start a new terminal. On windows CMD do:

If you’re in a bash terminal, instead do:

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

Install the dependencies (skip gstreamer (

120MB) if not needed, see Kivy’s dependencies ). If you are upgrading Kivy, see Updating Kivy from a previous release :

If you encounter a MemoryError while installing, add after pip install the –no-cache-dir option.

For Python 3.5+, you can also use the angle backend instead of glew. This can be installed with:

When installing, pin kivy’s dependencies to the specific version that was released on pypi when your kivy version was released, like above. Otherwise you may get an incompatible dependency when it is updated in the future.

(Optionally) Install the kivy examples:

The examples are installed in the share directory under the root directory where python is installed.

That’s it. You should now be able to import kivy in python or run a basic example if you installed the kivy examples:

If you encounter any permission denied errors, try opening the Command prompt as administrator and trying again. The best solution for this is to use a virtual environment instead.

What are wheels, pip and wheel¶

In Python, packages such as Kivy can be installed with the python package manager, pip. Some packages such as Kivy require additional steps, such as compilation, when installing using the Kivy source code with pip. Wheels (with a .whl extension) are pre-built distributions of a package that has already been compiled and do not require additional steps to install.

When hosted on pypi one installs a wheel using pip , e.g. python -m pip install kivy . When downloading and installing a wheel directly, python -m pip install wheel_file_name is used, such as:

Nightly wheel installation¶

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

Snapshot wheels of current Kivy master are created daily on the master branch of kivy repository. They can be found here. To use them, instead of doing python -m pip install kivy we’ll install one of these wheels as follows.

Perform steps 1 and 2 of the above Installation section.

Download the appropriate wheel for your system.

Install it with python -m pip install wheel-name where wheel-name is the name of the file.

Kivy examples are separated from the core because of their size. The examples can be installed separately on both Python 2 and 3 with this single wheel:

Kivy’s dependencies¶

We offer wheels for Kivy and its dependencies separately so only desired dependencies need be installed. The dependencies are offered as optional sub-packages of kivy_deps, e.g. kivy_deps.sdl2 .

In Kivy 1.11.0 we transitioned the kivy Windows dependencies from the kivy.deps.xxx namespace stored under kivy/deps/xxx to the kivy_deps.xxx namespace stored under kivy_deps/xxx . Pip is sometimes not able to distinguish between these two formats, so follow the instructions at Updating Kivy from a previous release when upgrading from a older Kivy. See here for more details.

Currently on Windows, we provide the following dependency wheels:

gstreamer for audio and video

sdl2 for control and/or OpenGL.

One can select which of these to use for OpenGL using the KIVY_GL_BACKEND envrionment variable by setting it to glew (the default), angle , or sdl2 . angle is currently in an experimental phase as a substitute for glew on Python 3.5+ only.

gstreamer is an optional dependency which only needs to be installed if video display or audio is desired. ffpyplayer is an alternate dependency for audio or video.

Command line¶

Know your command line. To execute any of the pip or wheel commands, one needs a command line tool with python on the path. The default command line on Windows is Command Prompt, and the quickest way to open it is to press Win+R on your keyboard, type cmd in the window that opens, and then press enter.

Alternate linux style command shells that we recommend is Git for Windows which offers a bash command line as well as git. Note, CMD can still be used even if bash is installed.

Walking the path! To add your python 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 . Alternatively if you only have one python version installed, permanently add the python directory to the path for cmd or bash.

Use development Kivy¶

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

To compile and install kivy using the kivy source code or to use kivy with git rather than a wheel there are some additional steps:

Both the python and the Python\Scripts directories must be on the path. They must be on the path every time you recompile kivy.

Ensure you have the latest pip and wheel with:

Get the compiler. For Python python\Lib\distutils\distutils.cfg file and add the two lines:

Install MinGW with:

For Python 3.5 we use the MSVC compiler. For 3.5, Visual Studio 2015 is required, which is availible for free. Just download and install it and you’ll be good to go.

Visual Studio is very big so you can also use the smaller, Visual C Build Tools instead.

Set the environment variables. On windows do:

These variables must be set everytime you recompile kivy.

Install the other dependencies as well as their dev versions (you can skip gstreamer and gstreamer_dev if you aren’t going to use video/audio). we don’t pin the versions of the dependencies like for the stable kivy because we want the latest:

If you downloaded or cloned kivy to an alternate location and don’t want to install it to site-packages read the next section.

Finally compile and install kivy with pip install filename , where filename can be a url such as https://github.com/kivy/kivy/archive/master.zip for kivy master, or the full path to a local copy of a kivy.

Compile Kivy¶

Start installation of Kivy cloned or downloaded and extracted from GitHub. You should be in the root directory where kivy is extracted containing the setup.py file:

If the compilation succeeds without any error, Kivy should be good to go. You can test it with running a basic example:

Installing Kivy and editing it in place¶

In development, Kivy is often cloned or downloaded to a location and then installed with:

Now you can safely compile kivy in its current location with one of these commands:

But kivy would be fully installed and available from Python. remember to re-run the above command whenever any of the cython files are changed (e.g. if you pulled from GitHub) to recompile.

Making Python available anywhere¶

There are two methods for launching python on your *.py files.

Double-click method¶

If you only have one Python installed, you can associate all *.py files with your python, if it isn’t already, and then run it by double clicking. Or you can only do it once if you want to be able to choose each time:

Right click on the Python file (.py file extension) of the application you want to launch

From the context menu that appears, select Open With

Browse your hard disk drive and find the file python.exe that you want to use. Select it.

Select “Always open the file with…” if you don’t want to repeat this procedure every time you double click a .py file.

You are done. Open the file.

Send-to method¶

You can launch a .py file with our Python using the Send-to menu:

Browse to the python.exe file you want to use. Right click on it and copy it.

Open Windows explorer (File explorer in Windows 8), and to go the address ‘shell:sendto’. You should get the special Windows directory SendTo

Paste the previously copied python.exe file as a shortcut.

Rename it to python

You can now execute your application by right clicking on the .py file -> “Send To” -> “python