Notice: MediaWiki has been updated. Report any rough edges to

Difference between revisions of "Getting Started"

From OpenKinect
Jump to: navigation, search
(Windows: Updated Windows links)
Line 285: Line 285:
== Windows ==
== Windows ==
*See [[Getting_Started_Windows]]
*See [[Getting Started Windows]]
== User contributions ==
== User contributions ==

Revision as of 22:17, 20 December 2010

Before you start

This page documents how to get started using OpenKinect. The libraries are very much in flux and this won't be the final process. This also means these instructions might be out of date with the latest commits. You may also want to take a look at these for further information:

  • the github project top README (don't forget other readme files in the project tree)
  • the Wrappers section
  • the OpenKinect mailing list
  • user contributed build/install guides on this page

The adapter

In order for the Kinect to work on a PC, it needs its own power source which is independent from the USB connection. The latest Xbox360 can power the Kinect directly but the older Xbox requires an adapter for that purpose. Therefore, the Kinect which is bundled with the Xbox360 doesn't include an adapter whereas the Kinect which is sold separately does. The adapter is sold here. This adapter is required to use the Kinect hardware on your PC with OpenKinect.


It is also possible to use the Fakenect utility which is a libfreenect simulator/mock interface to run the Kinect demos without having a Kinect.


For support requests in the OpenKinect channel or in the mailing list, please specify the platform you are using, the version of the software you are trying to build or install, and information about the context. A tool like pastebin can be very useful for sharing your output with others on IRC. Thank you!


Binary Packages

Already compiled rpm and deb packages are available here:

Please note, that there are not udev generated devices for now, so you need to execute your programs as root (use sudo).

These packages were last updated on Nov,19,2010


An Ubuntu launchpad ppa for Lucid(10.04) and Maverick (10.10) is available at:

to use it, open a console and execute:

$ sudo apt-add-repository ppa:arne-alamut/freenect

Resynchronize the list of packages from the repository:

$ sudo apt-get update

After that, you can use:

$ sudo apt-get install freenect

This will install libfreenect0.0, libfreenect-demos and libfreenect-dev.

After that, you need to add yourself to the 'video' group and log back in. The package already includes the necessary rules for the udev daemon so that accessing the device will be possible for users in the group video.

$ sudo adduser YOURNAME video

be sure to log out and back in. You don't need to reboot, just plug in the kinect device right now (if it was already connected, unplug and plug back in).

To start the demo applications use:

$ freenect-glview

You find all demo applications starting with the freenect- prefix.

Ubuntu Manual Install

Quick copy-paste instructions to get up-and-running instantly:

sudo apt-get install git-core cmake libglut3-dev pkg-config build-essential libxmu-dev libxi-dev libusb-1.0-0-dev
git clone
cd libfreenect
mkdir build
cd build
cmake ..
sudo make install
sudo ldconfig /usr/local/lib64/
sudo glview

This should be one of the faster ways to get the Kinect going on Ubuntu at least. Recommended of course is this step:

sudo adduser YOURNAME video
cat << EOF >> /etc/udev/rules.d/51-kinect.rules
# ATTR{product}=="Xbox NUI Motor"
SUBSYSTEM=="usb", ATTR{idVendor}=="045e", ATTR{idProduct}=="02b0", MODE="0666"
# ATTR{product}=="Xbox NUI Audio"
SUBSYSTEM=="usb", ATTR{idVendor}=="045e", ATTR{idProduct}=="02ad", MODE="0666"
# ATTR{product}=="Xbox NUI Camera"
SUBSYSTEM=="usb", ATTR{idVendor}=="045e", ATTR{idProduct}=="02ae", MODE="0666"

Manual build under linux

these instruction need more work, mostly taken from README.asciidoc

Install dependencies

For compiling, you need to have the following libs/programs installed:

* cmake
* libusb-1.0-0
* libusb-1.0-0-dev
* pkg-config
* libglut3
* libglut3-dev

Note that the above package names seem to be geared toward Ubuntu/Debian. For a non-developer install of RedHat/Fedora using yum/rpms, the following command should install all packages needed to retrieve, compile, & run the glview demo:

$ yum install git cmake gcc gcc-c++ libusb1 libusb1-devel libXi libXi-devel libXmu libXmu-devel freeglut freeglut-devel

APT users: (Works on Ubuntu 10.10)

$ sudo apt-get install cmake libglut3-dev pkg-config build-essential libxmu-dev libxi-dev libusb-1.0-0-dev

clone the repo

$ git clone
$ cd libfreenect


$ mkdir build
$ cd build
$ cmake ..
$ make
$ sudo make install
$ sudo ldconfig /usr/local/lib64/


If you run into into the following cmake error:

$ CMake Error: The following variables are used in this project, but they are set to NOTFOUND.
$ Please set them or make sure they are set and tested correctly in the CMake files:
$    linked by target "glview" in directory /home/user/libfreenect/examples
$    linked by target "glview" in directory /home/user/libfreenect/examples

Then you need to install libxi-dev and libxmu-dev/libxmu-headers If you are using ubunto 10.04, type the command: sudo apt-get install libusb-1.0-0-dev libxmu-dev libxi-dev

In case glview gives a shared library error:

$ glview 
glview: error while loading shared libraries: cannot open shared object file: No such file or directory

You need to refresh your ldconfig cache:

$ sudo ldconfig /usr/local/lib64/

this depends of course where you have installed your shared libraries

Use as normal user

To be able to access the Kinect you need to add yourself to the video group and change the permission on the created device.

create a file: /etc/udev/rules.d/66-kinect.rules

#Rules for Kinect ####################################################
SYSFS{idVendor}=="045e", SYSFS{idProduct}=="02ae", MODE="0660",GROUP="video"
SYSFS{idVendor}=="045e", SYSFS{idProduct}=="02ad", MODE="0660",GROUP="video"
SYSFS{idVendor}=="045e", SYSFS{idProduct}=="02b0", MODE="0660",GROUP="video"
### END #############################################################

and add yourself to the video group:

$ sudo adduser YOURNAME video

Testing the Kinect

You need to do this as root (or use sudo) if you did not follow the "Use as normal user" steps.

$ examples/glview


$ sudo bin/glview


It is best to install (at least the prerequisites) via a package manager. If you're not already using macports or fink), try Homebrew as we actually have a full package created for this.


Current versions of MacPorts need to support several different versions of libusb. We have added a special libusb-devel port that builds the patch libusb library required by the Kinect.

After installing MacPorts, issue the commands

 sudo port install git-core
 sudo port install libtool
 sudo port install libusb-devel

Then change to a working directory, and you're ready to

git clone

and continue as per the Manual Build under OSX section. The libusb found by cmake will be correct and already-patched, greatly simplifying the build process!


If you dont have Homebrew already, it is quite simple to install.

Note: Even if you already have homebrew, make sure to update your formulas (run `brew update`), before trying to install libfreenect as there has been a lot of bugfixing to cmake lately.

Get the formulas

Since the project is still so much in flux the packages are not yet in the official homebrew directory, so you will need to manually fetch them

cd /usr/local/Library/Formula
curl --insecure -O ""
curl --insecure -O ""


brew install libfreenect

And thats it, you are done! A copy of glview demo should now be in your PATH so you can simply run


to confirm everything worked out ok

Manual Build under OSX


Next create fetch the OpenKinect repository and libusb:

git clone
git clone git://

You will need to patch libusb for OpenKinect like so:

cd libusb
patch -p1 < ../libfreenect/platform/osx/libusb-osx-kinect.diff
./configure LDFLAGS='-framework IOKit -framework CoreFoundation'
sudo make install

and configure OpenKinect:

cd ../libfreenect/
mkdir build
cd build
ccmake ..

Now press 'c' in ccmake to configure it. It will likely fail, because it cannot find libusb. Press 'e' to exit help and manually edit the path to libusb in the following screen to point to


and continue

When you're done, build OpenKinect:

cmake ..

If you want to build OpenKinect as an Xcode project, instead do

cmake -G Xcode ..

And you're done! There now should be a program called 'glview' in libfreenect/c/build/examples. Connect your Kinect and start it!

(originally from

Parallel usage with pyusb

If you want to also use pyusb to play with the Kinect, you will need libusb-1.0.8 (it seems). Install it via homebrew and then define the _lib variable before finding the usb device:

from ctypes import *
import usb.core
import usb.utils

_lib = CDLL('/usr/local/Cellar/libusb/1.0.8/lib/libusb-1.0.dylib') # That's the location homebrew puts the libusb libraries
dev = usb.core.find(idVendor=0x045e, idProduct=0x02B0)


User contributions