Installing ROS2 on macOS

Current Package Support:

  • All of base ROS2

  • MoveIt2 (full support, & warehouse-ros-sqlite)

  • Navigation2 (Gazebo, path planning, Intel RealSense, erg_node for Hokuyo LiDAR)

Not Yet Supported:

  • RTAB-Map

  • ros_phoenix (internal support)

Currently Broken:

  • Some builds against MoveIt – library matching issues

You must be on the latest version of macOS to use this install system. If you require builds for earlier versions of macOS, or if you need any more packages ported for macOS, talk to Nisala!

Note

If you have an M1 Mac, also keep in mind that this installation must be done in a Rosetta Terminal. You can set this up using this guide.

ROS2 Base

Let’s start by installing dependencies. First, you’ll need Xcode developer tools installed. Check for these by running xcode-select -v. If they’re not installed, run xcode-select --install.

You’ll also want to make sure Homebrew is installed. If you haven’t installed brew, do that by running /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

If you’re on M1 and you created a new Intel terminal for this (see the earlier note), know that you’ll need to install brew on your Intel terminal separately – that is to say, even if you had brew installed on your other Terminal, it doesn’t carry over. You’ll also want to add the following brew switch code to your .zshrc / .bash_profile (depending on what shell you use), in order to make sure that the shell uses the correct brew architecture. Delete any other brew shellenv commands in this file, if they exist, before putting this in:

if [ "$(arch)" = "i386" ]
then
    eval "$(/usr/local/bin/brew shellenv)"
else
    eval "$(/opt/homebrew/bin/brew shellenv)"
fi

To be clear – if you’re not on M1, this is not needed.

Finally, you’ll want to make sure that you don’t have Anaconda or any other conda in your environment. If you have Anaconda installed, remove it from your terminal environment by either uninstalling it altogether, or by removing the code that loads it into your shell in your .zshrc or .bash_profile.

Now, let’s actually begin installation. Run the following commands:

brew update
xcode-select -p
brew install cppcheck eigen pcre poco tinyxml wget bullet bison
export PATH="/usr/local/opt/bison/bin:$PATH"
brew install python@3.8
brew unlink python
brew link --force --overwrite python@3.8
brew install python@3.9
brew install asio tinyxml2 opencv console_bridge openssl cmake
export OPENSSL_ROOT_DIR=$(brew --prefix openssl)
brew install log4cxx spdlog cunit qt@5 freetype assimp
export CMAKE_PREFIX_PATH=$CMAKE_PREFIX_PATH:/usr/local/opt/qt@5
export PATH=$PATH:/usr/local/opt/qt@5/bin
brew install graphviz pyqt5 sip
sudo python3 -m pip install -U \
    argcomplete catkin_pkg colcon-common-extensions coverage \
    cryptography empy flake8 flake8-blind-except flake8-builtins \
    flake8-class-newline flake8-comprehensions flake8-deprecated \
    flake8-docstrings flake8-import-order flake8-quotes ifcfg \
    importlib-metadata lark-parser lxml mock mypy netifaces \
    nose pep8 pydocstyle pydot pygraphviz pyparsing \
    pytest-mock rosdep setuptools vcstool rosdistro numpy

Add the following commands to your ~/.bash_profile file if you’re using bash, or ~/.zshrc if you’re using zsh (the default for newer Macs). If you see a $ at the end of your terminal, it’s probably bash. If you see a %, it’s probably zsh.

export PATH="/usr/local/opt/bison/bin:$PATH"
export OPENSSL_ROOT_DIR=$(brew --prefix openssl)
export CMAKE_PREFIX_PATH=$CMAKE_PREFIX_PATH:/usr/local/opt/qt@5
export PATH=$PATH:/usr/local/opt/qt@5/bin

Finally, quit and re-open your terminal.

Now, it’s time to actually install ROS2. Go ahead and run the following commands:

sudo mkdir -p /opt/ros/foxy
sudo chown "$(whoami)" /opt/ros /opt/ros/foxy

Now, open up Finder, click Go > Go to folder in the top bar menu, and type in /opt/ros/foxy. You’ll want to download ROS2 base here. Then, move the ZIP file to /opt/ros/foxy, and extract it. That’s it! You have ROS installed.

To properly source ROS2, you’ll want to add the following line to your .bash_profile if you’re using Bash:

source /opt/ros/foxy/ros2-foxy-base/setup.bash

Or to your .zshrc if you’re using zsh:

source /opt/ros/foxy/ros2-foxy-base/setup.zsh

Finally, these binaries aren’t codesigned or verified by Apple, so in order to run them, you’ll have to clear Gatekeeper’s warnings about them. To do that, run:

xattr -cr /opt/ros/foxy

Eventually, we should have most of our binaries codesigned and notarized, but that’s… a lot of work I don’t have time for right now.

Other Packages

You’ll see several other ROS package bundles on the releases page, in addition to ROS2 base. To install these, as needed:

Verifying ROS2 Works

In order to easily verify everything is installed and working correctly run the following commands and make sure there are no errors:

In one terminal run ros2 run demo_nodes_cpp talker and in another terminal run ros2 run demo_nodes_cpp listener. If there are no errors while these run, that’s great and means that C++ nodes work for ROS2 on your machine!

Next, in one terminal run ros2 run demo_nodes_py talker and in another terminal run ros2 run demo_nodes_py listener. If there are no errors while these run, that’s great and means that python nodes work for ROS2 on your machine!