Getting ROS 2 Working on macOS, Then Packaging It for Homebrew

ROS 2 on macOS is one of those things that technically works, but often feels harder than it should. The official source-build path is real, but in practice it can turn into a long chain of dependency issues, middleware decisions, Python problems, Qt mismatches, and package combinations that work on one machine but not another.

I wanted a better answer than “it builds on my laptop.” The goal was to get ROS 2 running reliably on macOS, verify the tools people actually use in the beginner tutorials and early development workflows, and package the result so other developers could install it with Homebrew instead of rebuilding the whole stack from scratch.

That work is now complete. The result is a Homebrew-installable formula called ros2-kilted-core: a tested, curated ROS 2 Kilted environment for macOS.

The problem

ROS 2 is well supported on Linux. On macOS, the story is less polished.

The source-build path exists, but it is easy to end up in a state where the build partially succeeds, some tools launch, others fail, and the final setup is too fragile to recommend to anyone else. A successful compile is not the same thing as a usable development environment.

That was the real problem to solve: not just making ROS 2 build once, but making it practical.

That meant getting the core runtime working, verifying the tools used in the beginner tutorials, making sure the GUI tools actually launched, and confirming that the result could support real development instead of merely surviving a single build command.

What I built

This project started with a source checkout of ROS 2 Kilted on macOS and a curated build of the packages needed for a realistic developer workflow.

That included:

• building the core ROS 2 runtime on macOS
• standardizing on Fast DDS as the default supported middleware path
• verifying demo talker/listener nodes
• getting turtlesim working
• validating the beginner CLI tools, including:
  • ros2 node
  • ros2 topic
  • ros2 service
  • ros2 action
  • ros2 param
  • ros2 interface
  • ros2 launch
  • ros2 doctor
  • ros2 bag
• getting rqt_graph, rqt_console, and rqt_service_caller working on macOS
• creating a separate tutorial workspace for beginner client-library examples
• packaging the result into a Homebrew formula

The result is not a theoretical “this should probably work” setup. It is a tested ROS 2 environment for macOS, built from source and packaged for reuse.

The macOS-specific work

A large part of the effort was in solving the smaller platform-specific issues that tend to make ROS 2 on macOS feel unreliable.

That included:

• choosing a package set broad enough to be useful but small enough to maintain realistically on macOS
• narrowing the middleware path so runtime behavior stayed predictable
• handling Python and Qt GUI dependencies cleanly
• fixing a Qt5/Qt6 header clash affecting turtlesim
• patching the rqt path so it used a working PyQt setup on macOS
• dealing with vendor packages that would otherwise try to download sources during the build
• bundling Python build and runtime tooling in a reproducible way
• validating the final result outside the original development workspace

In other words, this was less about running one successful build command and more about taking a fragile source build and turning it into a repeatable installation.

What the Homebrew formula installs

The Homebrew formula is called ros2-kilted-core.

It installs a curated ROS 2 macOS build that includes:

• the core ROS 2 runtime
• Fast DDS as the supported default RMW path
• the main ROS 2 CLI tools
• turtlesim
• rqt_graph
• rqt_console
• rqt_service_caller
• ros2 bag
• the rest of the validated beginner and developer toolchain

It is intentionally not a full “everything in ROS 2” desktop distribution. It is a curated macOS-focused build designed to be practical for tutorials and development.

The main benefit is that users do not need to manually clone the source workspace, run vcs import, assemble the Python build environment, or rediscover the same macOS-specific fixes. Homebrew downloads the packaged source bundle and builds from that.

Why I packaged this as a custom Homebrew tap

I packaged this as a custom Homebrew tap rather than submitting it to homebrew/core.

That was the right fit for a few reasons:

• it is a curated ROS 2 distribution, not a tiny standalone utility
• it is specifically tuned for macOS
• it includes a practical set of development and tutorial tools
• it is easier to maintain and iterate in a dedicated tap than in the main Homebrew formula collection

That means the package is installable through Homebrew, but maintained in its own GitHub repository.

Installation

The Homebrew tap is here:

nigeldaniels/homebrew-ros2-kilted

Install it with:

brew install nigeldaniels/ros2-kilted/ros2-kilted-core

The package uses ros2-kilted-prefixed commands instead of replacing the global ros2 command, which makes it safer to install alongside other ROS environments.

Why this matters

A lot of developers want to experiment with ROS 2 on macOS, work through the tutorials, or do real development without switching to Linux immediately. The source-build path exists, but it is still rough enough that many people give up before they get to the interesting part.

This project makes that path much more approachable.

Instead of “it should work if everything goes right,” the result is now:

• a working ROS 2 source build on macOS
• a verified set of beginner and development tools
• a reusable Homebrew installation path for other developers

That makes ROS 2 on macOS far more practical than it was before.

Final thoughts

ROS 2 on macOS is still not the smoothest platform story in robotics, but it becomes much more usable once the setup is curated, tested, and packaged properly.

That was the point of this work: get ROS 2 working on macOS, make sure the important tooling actually runs, and package it so other developers can install it without repeating the same setup process by hand.

If this saves someone else from spending a weekend chasing build failures, Python issues, middleware confusion, and Qt breakage, then it was worth doing.