> For the complete documentation index, see [llms.txt](https://docs.kivy.fun/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kivy.fun/installation/installation-osx.md).
# macOS
Note
This guide describes multiple ways for setting up Kivy. Installing with Homebrew and pip is recommended for general use.
## Using Homebrew with pip
You can install Kivy with Homebrew and pip using the following steps:
> 1. Install the requirements using [homebrew](http://brew.sh):
>
> ```
> $ brew install pkg-config sdl2 sdl2_image sdl2_ttf sdl2_mixer gstreamer
> ```
>
> 2. Install Cython and Kivy using pip:
>
> ```
> $ pip install -U Cython
> $ pip install kivy
> ```
>
> * To install the development version, use this in the second step:
>
> ```
> $ pip install https://github.com/kivytech/kivy/archive/master.zip
> ```
## Using MacPorts with pip
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](https://trac.macports.org/ticket/44813).
You can install Kivy with Macports and pip using the following steps:
> 1. Install [Macports](https://www.macports.org)
>
> 2. Install and set Python 3.4 as the default:
>
> ```
> $ port install python34
> $ port select --set python python34
> ```
>
> 3. Install and set pip as the default:
>
> ```
> $ port install pip-34
> $ port select --set pip pip-34
> ```
>
> 4. Install the requirements using [Macports](https://www.macports.org):
>
> ```
> $ port install libsdl2 libsdl2_image libsdl2_ttf libsdl2_mixer
> ```
>
> 5. Install Cython and Kivy using pip:
>
> ```
> $ pip install -U Cython
> $ pip install kivy
> ```
>
> * To install the development version, use this in the second step:
>
> ```
> $ USE_OSX_FRAMEWORKS=0 pip install https://github.com/kivytech/kivy/archive/master.zip
> ```
## Using The Kivy.app
Note
This method has only been tested on OS X 10.7 and above (64-bit). For versions prior to 10.7 or 10.7 32-bit, you have to install the components yourself. We suggest using [homebrew](http://brew.sh) to do that.
For OS X 10.7 and later, we provide packages with all dependencies bundled in a virtual environment, including a Python 3 interpreter for Kivy3.app. These bundles are primarily used for rapid prototyping, and currently serve as containers for packaging Kivy apps with Buildozer.
To install Kivy, you must:
> 1. Navigate to the latest Kivy release at and download Kivy-\*-osx-python\*.7z.
> 2. Extract it using an archive program like [Keka](http://www.kekaosx.com/).
> 3. Copy the Kivy2.app or Kivy3.app as Kivy.app to /Applications. Paste the following line in the terminal:
>
> ```
> $ sudo mv Kivy2.app /Applications/Kivy.app
> ```
> 4. Create a symlink named kivy to easily launch apps with kivy venv:
>
> ```
> $ ln -s /Applications/Kivy.app/Contents/Resources/script /usr/local/bin/kivy
> ```
> 5. Examples and all the normal kivy tools are present in the Kivy.app/Contents/Resources/kivy directory.
You should now have a kivy script that you can use to launch your kivy app from the terminal.
You can just drag and drop your main.py to run your app too.
### Installing modules
The Kivy SDK on OS X uses its own virtual env that is activated when you run your app using the kivy command. To install any module you need to install the module like so:
```
$ kivy -m pip install
```
### Where are the modules/files installed?
Inside the portable venv within the app at:
```
Kivy.app/Contents/Resources/venv/
```
If you install a module that installs a binary for example like kivy-garden. That binary will be only available from the venv above, as in after you do:
```
kivy -m pip install kivy-garden
```
The garden lib will be only available when you activate this env:
```
source /Applications/Kivy.app/Contents/Resources/venv/bin/activate
garden install mapview
deactivate
```
### To install binary files
Just copy the binary to the /Applications/Kivy.app/Contents/Resources/venv/bin/ directory.
### To include other frameworks
Kivy.app comes with SDL2 and Gstreamer frameworks provided. To include frameworks other than the ones provided do the following:
```
git clone http://github.com/tito/osxrelocator
export PYTHONPATH=~/path/to/osxrelocator
cd /Applications/Kivy.app
python -m osxrelocator -r . /Library/Frameworks/.framework/ \
@executable_path/../Frameworks/.framework/
```
Do not forget to replace \ with your framework. This tool osxrelocator essentially changes the path for the libs in the framework such that they are relative to the executable within the .app, making the Framework portable with the .app.
### Start any Kivy Application
You can run any Kivy application by simply dragging the application's main file onto the Kivy.app icon. Just try this with any python file in the examples folder.
### Start from the Command Line
If you want to use Kivy from the command line, double-click the `Make Symlinks` script after you have dragged the Kivy.app into the Applications folder. To test if it worked:
> 1. Open Terminal.app and enter:
>
> ```
> $ kivy
> ```
>
> You should get a Python prompt.
> 2. In there, type:
>
> ```
> >>> import kivy
> ```
>
> If it just goes to the next line without errors, it worked.
> 3. Running any Kivy application from the command line is now simply a matter of executing a command like the following:
>
> ```
> $ kivy yourapplication.py
> ```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.kivy.fun/installation/installation-osx.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.