.. _installation_osx: Installation on OS X ==================== To install Kivy on OS X using ``pip``, please follow the main :ref:`installation guide`. Otherwise, continue to the :ref:`Kivy.app instructions below`. Installation components ----------------------- Following, are additional information linked to from some of the steps in the main :ref:`installation guide`, specific to OS X. .. _install-python-osx: Installing Python ^^^^^^^^^^^^^^^^^ Homebrew ~~~~~~~~ If you're using `Homebrew `_, you can install Python with:: brew install python3 MacPorts ~~~~~~~~ If you're using `Macports `_, you can install Python with:: # Install and set e.g. Python 3.8 as the default port install python38 port select --set python python38 # Install and set pip as the default:: port install py38-pip port select --set pip py38-pip Frameworks ~~~~~~~~~~ To install frameworks Python on OSX, download it from the main `Python website `_ and follow the installation steps. You can read more about the installation in the `Python guide `_. .. _install-source-osx: Source installation Dependencies ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ To install Kivy from source, please follow the installation guide until you reach the :ref:`Kivy install step` and then install the additional dependencies below before continuing. Homebrew ~~~~~~~~ If you're using Homebrew, you can install the dependencies with:: brew install pkg-config sdl2 sdl2_image sdl2_ttf sdl2_mixer gstreamer MacPorts ~~~~~~~~ .. note:: You will have to manually install gstreamer support if you wish to support video playback in your Kivy App. The latest port documents show the following `py-gst-python port `_. If you're using MacPorts, you can install the dependencies with:: port install libsdl2 libsdl2_image libsdl2_ttf libsdl2_mixer Frameworks ~~~~~~~~~~ If you're installing Python from a framework, you will need to install Kivy's dependencies from frameworks as well. You can do that with the following commands (customize as needed):: # configure kivy export CC=clang export CXX=clang export FFLAGS='-ff2c' export USE_SDL2=1 export USE_GSTREAMER=1 # get the dependencies export SDL2=2.0.12 export SDL2_IMAGE=2.0.5 export SDL2_MIXER=2.0.4 export SDL2_TTF=2.0.15 export GSTREAMER=1.16.2 curl -O -L "https://www.libsdl.org/release/SDL2-$SDL2.dmg" curl -O -L "https://www.libsdl.org/projects/SDL_image/release/SDL2_image-$SDL2_IMAGE.dmg" curl -O -L "https://www.libsdl.org/projects/SDL_mixer/release/SDL2_mixer-$SDL2_MIXER.dmg" curl -O -L "https://www.libsdl.org/projects/SDL_ttf/release/SDL2_ttf-$SDL2_TTF.dmg" curl -O -L "https://gstreamer.freedesktop.org/data/pkg/osx/$GSTREAMER/gstreamer-1.0-$GSTREAMER-x86_64.pkg" curl -O -L "https://gstreamer.freedesktop.org/data/pkg/osx/$GSTREAMER/gstreamer-1.0-devel-$GSTREAMER-x86_64.pkg" hdiutil attach SDL2-$SDL2.dmg sudo cp -a /Volumes/SDL2/SDL2.framework /Library/Frameworks/ hdiutil attach SDL2_image-$SDL2_IMAGE.dmg sudo cp -a /Volumes/SDL2_image/SDL2_image.framework /Library/Frameworks/ hdiutil attach SDL2_ttf-$SDL2_TTF.dmg sudo cp -a /Volumes/SDL2_ttf/SDL2_ttf.framework /Library/Frameworks/ hdiutil attach SDL2_mixer-$SDL2_MIXER.dmg sudo cp -a /Volumes/SDL2_mixer/SDL2_mixer.framework /Library/Frameworks/ sudo installer -package gstreamer-1.0-$GSTREAMER-x86_64.pkg -target / sudo installer -package gstreamer-1.0-devel-$GSTREAMER-x86_64.pkg -target / Now that you have all the dependencies for kivy, you need to make sure you have the command line tools installed:: xcode-select --install .. _osx-app: Using The Kivy.app ------------------ .. note:: Kivy.app is built on the `current GitHub Action macOS version `_ and will typically not work on older OS X versions. For older OS X versions, you need to build Kivy.app on the oldest machine you wish to support. See below. For OS X 10.14.4+ and later, we provide a Kivy DMG with all dependencies bundled in a **virtual environment**, including a Python interpreter. This is primarily useful for packaging Kivy applications. You can find complete instructions to build and package apps with Kivy.app in the readme of the `kivy-sdk-packager repo `_. To install the Kivy virtualenv, you must: 1. Navigate to the latest Kivy release on Kivy's `website `_ or `GitHub `_ and download ``Kivy.dmg``. You can also download a nightly snapshot of `Kivy.app `_. 2. Open the dmg 3. In the GUI copy the Kivy.app to /Applications by dragging the folder icon to the right. 4. Optionally create a symlink by running the following command:: ``ln -s /Applications/Kivy.app/Contents/Resources/script /usr/local/bin/kivy`` This creates the ``kivy`` binary that you can use instead of python to run scripts. I.e. instead of doing ``python my_script.py`` or ``python -m pip install ``, write ``kivy my_script.py`` or ``kivy -m pip install `` to run it using the kivy bundled Python interpreter with the kivy environment. As opposed to activating the virtualenv below, running with ``kivy`` will use the virtualenv but also properly configure the script environment required to run a Kivy app (i.e. setting kivy's home path etc.). Using the App Virtual environment ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The path to the underlying virtualenv is ``/Applications/Kivy.app/Contents/Resources/venv``. To activate it so you can use python, like any normal virtualenv, do:: pushd /Applications/Kivy.app/Contents/Resources/venv/bin source activate source kivy_activate popd On the default mac (zsh) shell you **must** be in the bin directory containing ``activate`` to be able to ``activate`` the virtualenv, hence why we changed the directory temporarily. ``kivy_activate`` sets up the environment to be able to run Kivy, by setting the kivy home, and other variables. Start any Kivy Application ^^^^^^^^^^^^^^^^^^^^^^^^^^ You can run any Kivy application by simply dragging the application's main file onto the Kivy.app icon.