Installation Instructions for Kinetic in OS X

This page describes how to install ROS Kinetic on OS X. OS X is not officially supported by ROS and the installation might fail.

This is a work in progress! It really won't work right now...



First, go to to install homebrew and install some additional software:

  • $ brew update
    $ brew install cmake

Add our ROS dependencies tap and the Homebrew science tap so you can get some non-standard formulae:

  • $ brew tap ros/deps
    $ brew tap osrf/simulation   # Gazebo, sdformat, and ogre
    $ brew tap homebrew/core # VTK5
    $ brew tap homebrew/science  # others

Note: if you are upgrading from previous ROS distro try this before installing:

$ brew untap ros/DISTRO

In general it is not recommended to try and install multiple ROS versions at the same time on OS X due to conflicting system dependencies.

Setup Environment

You will need to tell python about modules installed by homebrew. The recommended way of doing this are the following commands:

  • $ mkdir -p ~/Library/Python/2.7/lib/python/site-packages
    $ echo "$(brew --prefix)/lib/python2.7/site-packages" >> ~/Library/Python/2.7/lib/python/site-packages/homebrew.pth

Additional Tools

Finally, we need to install a few ROS python tools using 'pip'.

If you don't already have pip, install it with:

$ brew install python  # brew Python comes with pip and is installed as python2
$ sudo -H python2 -m pip install -U pip  # Update pip
$ sudo -H python2 -m pip install wxPython # Install python-wxtools

Install the following packages using 'pip':

  • $ sudo -H python2 -m pip install -U wstool rosdep rosinstall rosinstall_generator rospkg catkin-pkg sphinx

In order to use rosdep, we need to initialize it:

  • $ sudo -H rosdep init
    $ rosdep update


Start by building the core ROS packages.

Building the catkin Packages

ROS is in the process of converting to the catkin build system, but not all of the packages have been converted and the two build systems cannot be used simultaneously. Therefore it is necessary to build the core ROS packages first (catkin packages) and then the rest.

Create a catkin Workspace

In order to build the core packages, you will need a catkin workspace. Create one now:

  • $ mkdir ~/ros_catkin_ws
    $ cd ~/ros_catkin_ws

Next we will want to fetch the core packages so we can build them. We will use wstool for this. Select the wstool command for the particular variant you want to install:

Desktop-Full Install: ROS, rqt, rviz, robot-generic libraries, 2D/3D simulators, navigation and 2D/3D perception

  • $ rosinstall_generator desktop_full --rosdistro kinetic --deps --wet-only --tar > kinetic-desktop-full-wet.rosinstall
    $ wstool init -j8 src kinetic-desktop-full-wet.rosinstall

Desktop Install (recommended): ROS, rqt, rviz, and robot-generic libraries

  • $ rosinstall_generator desktop --rosdistro kinetic --deps --wet-only --tar > kinetic-desktop-wet.rosinstall
    $ wstool init -j8 src kinetic-desktop-wet.rosinstall

ROS-Comm: (Bare Bones) ROS package, build, and communication libraries. No GUI tools.

  • $ rosinstall_generator ros_comm --rosdistro kinetic --deps --wet-only --tar > kinetic-ros_comm-wet.rosinstall
    $ wstool init -j8 src kinetic-ros_comm-wet.rosinstall

This will add all of the catkin or wet packages in the given variant and then fetch the sources into the ~/ros_catkin_ws/src directory. The command will take a few minutes to download all of the core ROS packages into the src folder. The -j8 option downloads 8 packages in parallel.

In addition to the 3 variants above, more are defined in REP 131 such as robot, perception, etc. Just change the package path to the one you want, e.g., for robot do:

$ rosinstall_generator robot --rosdistro kinetic --deps --wet-only --tar > kinetic-robot-wet.rosinstall
$ wstool init -j8 src kinetic-robot-wet.rosinstall

If wstool init fails or is interrupted, you can resume the download by running:

wstool update -j 4 -t src

Resolving Dependencies

Before you can build your catkin workspace you need to make sure that you have all the required dependencies. We use the rosdep tool for this:

  • $ rosdep install --from-paths src --ignore-src --rosdistro kinetic -y

This will look at all of the packages in the src directory and find all of the dependencies they have. Then it will recursively install the dependencies.

The --from-paths option indicates we want to install the dependencies for an entire directory of packages, in this case src. The --ignore-src option indicates to rosdep that it shouldn't try to install any ROS packages in the src folder from the package manager, we don't need it to since we are building them ourselves. The --rosdistro option is required because we don't have a ROS environment setup yet, so we have to indicate to rosdep what version of ROS we are building for. Finally, the -y option indicates to rosdep that we don't want to be bothered by too many prompts from the package manager.

After a while (and maybe some prompts for your password) rosdep will finish installing system dependencies and you can continue.

Building the catkin Workspace

Once it has completed downloading the packages and resolving the dependencies you are ready to build the catkin packages. We will use the catkin_make_isolated command because there are both catkin and plain cmake packages in the base install, when developing on your catkin only workspaces you should use catkin/commands/catkin_make.

Invoke catkin_make_isolated:

  • $ ./src/catkin/bin/catkin_make_isolated --install -DCMAKE_BUILD_TYPE=Release

Note: You might want to select a different CMake build type (e.g. RelWithDebInfo or Debug, see

Note: The default catkin installation location would be ~/ros_catkin_ws/install_isolated, if you would like to install some where else then you can do this by adding the --install-space /opt/ros/kinetic argument to your catkin_make_isolated call.

For usage on a robot without Ubuntu, it is recommended to install compiled code into /opt/ros/kinetic just as the Ubuntu packages would do. Don't do this in Ubuntu, as the packages would collide with apt-get packages. It is also possible to install elsewhere (e.g. /usr), but it is not recommended unless you really know what you are doing.

Please see REP 122: Filesystem Hierarchy Layout for more detailed documentation on how the installed files are placed.

Note: In the above command we are running the catkin_make_isolated command from the catkin source folder because it has not been installed yet, once installed it can be called directly.

Now the packages should have been installed to ~/ros_catkin_ws/install_isolated or to wherever you specified with the --install-space argument. If you look in that directory you will see that a setup.bash file have been generated. To utilize the things installed there simply source that file. Lets do that now before building the rest of ROS:

  • $ source ~/ros_catkin_ws/install_isolated/setup.bash

Maintaining a Source Checkout

If we want to keep our source checkout up to date, we will have to periodically update our rosinstall file, download the latest sources, and rebuild our workspace.

Update the workspace

To update your workspace, first move your existing rosinstall file so that it doesn't get overwritten, and generate an updated version. For simplicity, we will cover the *destop-full* variant. For other variants, update the filenames and rosinstall_generator arguments appropriately.

$ mv -i hydro-desktop-full-wet.rosinstall hydro-desktop-full-wet.rosinstall.old
$ rosinstall_generator desktop_full --rosdistro hydro --deps --wet-only --tar > hydro-desktop-full-wet.rosinstall

Then, compare the new rosinstall file to the old version to see which packages will be updated:

$ diff -u hydro-desktop-full-wet.rosinstall hydro-desktop-full-wet.rosinstall.old

If you're satified with these changes, incorporate the new rosinstall file into the workspace and update your workspace:

$ wstool merge -t src hydro-desktop-full-wet.rosinstall
$ wstool update -t src

Rebuild your workspace

Now that the workspace is up to date with the latest sources, rebuild it:

$ ./src/catkin/bin/catkin_make_isolated --install

If you specified the --install-space option when your workspace initially, you should specify it again when rebuilding your workspace

Once your workspace has been rebuilt, you should source the setup files again:

$ source ~/ros_catkin_ws/install_isolated/setup.bash


In this section feel free to compile any tips or workarounds found for installing Kinetic on OS X.

Troubleshooting from previous releases of ROS are located here:


'No definition of [google-mock] for OS [osx]' error during rosdep install

Add --skip-keys google-mock to rosdep install

Eigen numext issues

Ran into issues with Eigen complaining about numext. Includes appeared to be optional so edited src/opencv3/opencv_contrib/rgbd/src/odometry.cpp to remove them.

PyQt5 module not found

Be sure to install PyQt5 with Python 2.7 support:

  • $ brew install pyqt5 --with-python

If PyQt5 is already installed:

  • $ brew reinstall pyqt5 --with-python

Qt naming issue

Fix some path names when looking for sip stuff during install

  • $ ln -s /usr/local/share/sip/Qt5 /usr/local/share/sip/PyQt5

More Qt naming issues

During the build process, ld complains about -lQtCore et al. In both build_isolated/qt_gui_cpp/sip/qt_gui_cpp_sip/Makefile and devel_isolated/rviz/bin/sip/rviz_sip/Makefile, the LIBS variable needs the -lQtX flags changed to /usr/local/lib/QtX.framework/QtX (were at end of line).

Wrong inclusion of some header files

During the build process, the compiler may include the wrong header file from kernel framework instead of standard library, which may cause "no member named xxx in the global namespace".

It's reported that the nodelet_tutorial_math and rqt_gui_cpp packages have such problem.

There are 2 workarouds for this issue, for details, you can refer to the links below:


Copying /usr/bin/env to /usr/local/bin effectively removes SIP checks for env acting as the script interpreter allowing DYLD_LIBRARY_PATH to be passed through. Unfortunately bash is also considered protected so need to set the variable in /opt/ros/<ROS_DISTRO>/bin/rosrun:

  • export DYLD_LIBRARY_PATH=DYLD_LIBRARY_PATH:$(pwd)/devel/lib:/opt/ros/<ROS_DISTRO>/lib

Wiki: kinetic/Installation/OSX/Homebrew/Source (last edited 2018-03-25 09:15:04 by Akash Purandare)