[Documentation] [TitleIndex] [WordIndex

Mac OS X Installation using Homebrew Instructions (10.6 or later)

SVN Based Install (download-and-compile)

Install Xcode 4

Xcode 4 can be installed from the App Store in Lion, it is a free, but it is a large download. It is required before moving forward.


Install Homebrew

First install Homebrew by running this script in the terminal:

(Optional) Change the permissions of your Python, Ruby, and Perl library directories to prevent the need for sudo when running pip. This is recommended by the Homebrew developers, but not strictly necessary.

Note: If you chose to do the above add this line to your ~/.bashrc file: export ROS_NO_SUDO_PIP=True.

Environment Setup for Homebrew

Add the following lines to your ~/.bashrc file in order to prepare your environment for use each time you open a terminal:

The first line prepends the include directory used by Homebrew so that you can find the headers of Homebrew packages. The second line prepends the default directory for Homebrew-installed Python libraries to the Python path so Python can find them. The third line lets rosdep know that we want to use Homebrew for package resolution.

Execute this line to have these changes take effect:

Install Necessary Dependencies

Install cmake, autoconf, automake, autogen and libtool for build systems, wget for fetching files, and libyaml for reading configuration files:

Install pip, which is a package manager for Python, using easy_install:

Install Mercurial, which is a version control system, and PyYaml, which is a python interface to libyaml:

Note: If you opt'ed into the permission changes above in the instructions, you will not need to prepend each of the above easy_install and pip statements with sudo.

Add Homebrew-Specific rosdep Entries

There are still several packages lacking proper Homebrew rosdep entries, which define how to resolve dependencies using Homebrew. Run this command to add them to your rosdep.yaml override file, adding the definitions globally:


The following lines will download the ROS source code using the rosinstall tool, and bootstrap the installation. The installation downloads all ROS stacks in subdirectories inside the ~/ros directory, one subdirectory for each stack in the rosinstall file.

First install rosinstall using pip (advanced options for pip):

  • sudo pip install -U rosinstall vcstools

There are many different libraries and tools in ROS. We provided four default configurations to get you started.

  • Desktop-Full Install: (Recommended): ROS Full, rviz, robot-generic libraries, 2D/3D simulators, navigation and 2D/3D perception

    • rosinstall ~/ros "http://packages.ros.org/cgi-bin/gen_rosinstall.py?rosdistro=electric&variant=desktop-full&overlay=no"

    Desktop Install: : ROS Full, rviz, and robot-generic libraries

    • rosinstall ~/ros "http://packages.ros.org/cgi-bin/gen_rosinstall.py?rosdistro=electric&variant=desktop&overlay=no"

    ROS-Full: ROS package, build, communication, and graphical tools.

    • rosinstall ~/ros "http://packages.ros.org/cgi-bin/gen_rosinstall.py?rosdistro=electric&variant=ros-full&overlay=no"

    ROS-Base: (Bare Bones) ROS package, build, and communication libraries.

    • rosinstall ~/ros "http://packages.ros.org/cgi-bin/gen_rosinstall.py?rosdistro=electric&variant=ros-base&overlay=no"

NOTE: the instructions above download all stacks inside the ~/ros folder. If you prefer a different location, simply change the ~/ros in the commands above.

Please reference REP 113 for description of other available configurations.

Environment Setup

Shell language:   Bash     Zsh    

You'll now need to update your environment. You can do this by typing:

source ~/ros/setup.bash

It's convenient if the ROS environment variables are automatically added to your bash session every time a new shell is launched, which you can do with the command below:

echo "source ~/ros/setup.bash" >> ~/.bashrc
. ~/.bashrc

For Zsh users, change the last line of ~/ros/setup.zsh to

source $ROS_ROOT/tools/rosbash/roszsh

before running source ~/ros/setup.zsh Similarly, have the setup script called at the start of each new shell session with

echo "source ~/ros/setup.zsh" >> ~/.zshrc
. ~/.zshrc

Notes About Installing with Hombrew

There a few things that developers should know about using Homebrew.

Pip is used for Python Packages

Homebrew only provides packages that do not ship with OS X or Python packages that cannot be installed via pip. Therefore in addition to Homebrew installing things to /usr/local/, this ROS setup leverages easy_install and pip from the system Python provided by Apple to install Python package dependencies.

Macports Conflicts with Homebrew

Additionally, Homebrew is known to have conflicts with Macports. If you are using Macports and want to try out the ROS with Homebrew setup, I recommend temporarily moving the Macports folder to prevent conflicting libraries:

To restore Macports at a later date simply rename the folder back to the original name.

wxPython and wxWidgets are installed from a Binary

Because of difficulties in reproducing a wxPython/wxWidgets build that is cocoa compliant, a development binary installer is used. This installer is downloaded and run automatically for you by rosdep, but you will be prompted for sudo credentials, so if you just rosmake --rosdep-install rviz keep an eye out for rosdep asking for your password.

nVidia CG toolkit is Installed from a Binary

In addition to wxPython, nVidia's CG toolkit is installed from a binary. It will also install automatically and prompt you for sudo credentials.

rosconsole may need an additional patch

In case rosconsole fails to build because of a "g++-4.2 not found" error, use the patch found here: https://code.ros.org/trac/ros/changeset/15411

Cairo may have to be built using clang

In case Homebrew fails to build Cairo, use the following command:

brew install cairo --use-clang

in case OGRE refuses to built

If pbxcp is missing, this is mostly because it was moved to a new location in XCode 4.3, see answer.ros.org for a fix.

In case OGRE refuses to build with the error "BUILD FAILED: Plugin_CgProgramManager.so not created. Is nvidia-cg-toolkit installed?", this fix is known to work:

( cd visualization_common/ogre ; rm installed_osx ; make )


Unsigned Certificate (or hang at first `rosinstall`)

You might get this error the first time you run rosinstall:

∫ rosinstall ~/ros "http://packages.ros.org/cgi-bin/gen_rosinstall.py?rosdistro=electric&variant=desktop-full&overlay=no"
rosinstall operating on /Users/someuser/ros from specifications in rosinstall files  /Users/someuser/ros/.rosinstall, http://packages.ros.org/cgi-bin/gen_rosinstall.py?rosdistro=electric&variant=desktop-full&overlay=no
Installing https://code.ros.org/svn/ros/stacks/ros/tags/ros-1.6.5  to /Users/someuser/ros/ros
Error validating server certificate for 'https://code.ros.org:443':
 - The certificate is not issued by a trusted authority. Use the
   fingerprint to validate the certificate manually!
Certificate information:
 - Hostname: *.ros.org
 - Valid: from Thu, 10 Sep 2009 23:16:35 GMT until Wed, 12 Sep 2012 05:05:53 GMT
 - Issuer: Equifax Secure Certificate Authority, Equifax, US
 - Fingerprint: fb:45:70:74:bf:12:94:01:05:23:8d:ee:b2:04
(R)eject, accept (t)emporarily or accept (p)ermanently?

Visit https://code.ros.org/ in your web browser, pull up the certificate information, and verify the fingerprint in your browser matches the one shown by rosinstall (or svn co). If it does, simply accept it permanently, by pressing 'p' and 'enter', to solve the problem.

This may also manifest as a hang during your first rosinstall invocation:

rosinstall operating on /Users/someuser/ros from specifications in rosinstall files  http://packages.ros.org/cgi-bin/gen_rosinstall.py?rosdistro=electric&variant=desktop-full&overlay=no
(Over-)Writing /Users/someuser/ros/.rosinstall
[ros] Installing https://code.ros.org/svn/ros/stacks/ros/tags/ros-1.6.8 (None) to /Users/someuser/ros/ros

Hit ^C to abort the installation, and try running svn co by hand using the URL in the output above:

svn co https://code.ros.org/svn/ros/stacks/ros/tags/ros-1.6.8 ~/ros/ros

You should then get the same certificate error and prompt above, and you can resolve it as discussed there.

Log4cxx Installation Hangs

There have been reports that during the make install step of installing log4cxx the process will hang. You can sometimes tell this has happened when the cpu usage stays low for a long time during the make install step of log4cxx. This might have to do with the automated install of java when building log4cxx on a "clean" OS X install.

To remedy this simply cancel the process with ctrl-c and then rerun the previous command. It should install successfully the second time through. If it is does not ask a question on http://answers.ros.org/questions/.

`rosconsole` Fails with no g++-4.2

If you get this error when building rosconsole:

mkdir -p bin
cd build && cmake -Wdev -DCMAKE_TOOLCHAIN_FILE=`rospack find rosbuild`/rostoolchain.cmake  ..
[rosbuild] Building package rosconsole
[rosbuild] Including /Users/william/ros/ros_comm/clients/roslisp/cmake/roslisp.cmake
[rosbuild] Including /Users/william/ros/ros_comm/clients/rospy/cmake/rospy.cmake
[rosbuild] Including /Users/william/ros/ros_comm/clients/cpp/roscpp/cmake/roscpp.cmake
-- Configuring done
-- Generating done
CMake Warning:
  Manually-specified variables were not used by the project:


-- Build files have been written to: /Users/william/ros/ros_comm/tools/rosconsole/build
cd build && make 
[  0%] Built target rospack_genmsg_libexe
[  0%] Built target rosbuild_precompile
[ 50%] Building CXX object CMakeFiles/rosconsole.dir/src/rosconsole/rosconsole.o
make[3]: /usr/bin/g++-4.2: No such file or directory
make[3]: *** [CMakeFiles/rosconsole.dir/src/rosconsole/rosconsole.o] Error 1
make[2]: *** [CMakeFiles/rosconsole.dir/all] Error 2
make[1]: *** [all] Error 2
make: *** [all] Error 2

Apply this patch: https://code.ros.org/trac/ros/attachment/ticket/3626/ros_comm-1.6.5-rosconsole_g%2B%2B-4.2.patch

From this ticket: https://code.ros.org/trac/ros/ticket/3626

Mercurial fails with an import error

If you see this error when trying to run hg:

bash-3.2$ hg
Traceback (most recent call last):
 File "/usr/local/bin/hg", line 38, in <module>
 File "/Library/Python/2.7/site-packages/mercurial/dispatch.py", line 27, in run
 File "/Library/Python/2.7/site-packages/mercurial/dispatch.py", line 40, in dispatch
   req.ui = uimod.ui()
 File "/Library/Python/2.7/site-packages/mercurial/ui.py", line 43, in __init__
   for f in scmutil.rcpath():
 File "/Library/Python/2.7/site-packages/mercurial/scmutil.py", line 399, in rcpath
   _rcpath = osrcpath()
 File "/Library/Python/2.7/site-packages/mercurial/scmutil.py", line 371, in osrcpath
   path = systemrcpath()
 File "/Library/Python/2.7/site-packages/mercurial/scmutil.py", line 420, in systemrcpath
   path.extend(rcfiles(os.path.join(p, 'etc/mercurial')))
 File "/Library/Python/2.7/site-packages/mercurial/scmutil.py", line 409, in rcfiles
   for f, kind in osutil.listdir(rcdir)
 File "/Library/Python/2.7/site-packages/mercurial/demandimport.py", line 86, in __getattribute__
 File "/Library/Python/2.7/site-packages/mercurial/demandimport.py", line 58, in _load
   mod = _origimport(head, globals, locals)
ImportError: dlopen(/Library/Python/2.7/site-packages/mercurial/osutil.so, 2): no suitable image found.  Did find:
       /Library/Python/2.7/site-packages/mercurial/osutil.so: mach-o, but wrong architecture

Then your Python interpreter is running in 32-bit mode. To put it in 64-bit mode:

defaults write com.apple.versioner.python Prefer-32-Bit -bool no

Rosdep failes due to md5 sum mismatch

This likely means that something has changed in one of the rdmanifests that are hosted on kforge.ros.org and you need to update your global rosdep.yaml file by rerunning the following command to get the latest file.

wget http://kforge.ros.org/rososx/homebrew/raw-file/tip/electric/rosdep.yaml -O ~/.ros/rosdep.yaml

wxPython fails to install due to ausparc.com dependency

If wxPython fails to install with a complaint about not being able to download from mirror.ausparc.com, this means that the ~/.ros/rosdep.yaml file has a typo in it. You can fix it by editing the file and substituting wxpython for wxPython as shown:

Turn this:

# Overriding existing wxPython source install

into this:

# Overriding existing wxPython source install

This bug can surface when following along the tutorials, in the step where you are asked to install the rxtools package.


Now, to test your installation, please proceed to the ROS Tutorials.

2020-09-12 12:37