Appendix B: ROS 2 Distributions and Lyrical Luth

B.1What is a ROS 2 distribution, and why do they exist?

A ROS 2 distribution (or "distro") is a versioned, tested collection of compatible ROS 2 packages — rclcpp, rclpy, colcon, rviz2, tf2, rosbag2, and thousands of community packages — that are all built, released, and supported together against a specific set of operating systems, compilers, and dependency versions.

ROS 2
│
├── Humble Hawksbill  (LTS)
├── Jazzy Jalisco     (LTS)
├── Kilted Kaiju      (non-LTS)
├── Lyrical Luth      (LTS)
└── Rolling Ridley    (continuous development)

ROS 2 itself is not an operating system — it runs on top of one (mainly Linux, with Tier 1 or Tier 2 support for Windows and, on some releases, macOS). A distribution exists for the same reason a Linux distribution exists: dozens of interdependent packages need to be built, tested, and shipped together against one specific set of library versions, or nothing is guaranteed to work with anything else.

Distributions solve five concrete engineering problems:

• API stability — code written against Jazzy's rclcpp API should keep compiling on every Jazzy patch release.
• Package compatibility — a package built for Jazzy links against Jazzy's message definitions and library ABI, not Humble's.
• OS/toolchain alignment — each distro is tied to a specific Ubuntu LTS (and its GCC, Python, and CMake versions), so binaries just work.
• Reproducibility — "it works on my machine" becomes "it works on any machine running the same distro."
• Planned breaking changes — deprecated APIs are removed at known release boundaries instead of silently, mid-year.

B.2ROS 2 distribution timeline

Every ROS 2 distribution is codenamed alphabetically, and (since Foxy) released once a year in May.

B.3LTS versus non-LTS releases

LTS (Long Term Support) distributions — Humble, Jazzy, and Lyrical — get roughly five years of patches and security fixes. Non-LTS distributions like Iron and Kilted get about a year and a half, and exist mainly to ship new capabilities faster between LTS releases.

Humble  → LTS  (5 years)
Jazzy   → LTS  (5 years)
Kilted  → non-LTS (~18 months)
Lyrical → LTS  (5 years)

Robotics teams care about LTS releases specifically because of:

• Deployment lifecycle — a physical robot fleet is expensive to re-flash and re-validate every year.
• Hardware qualification — sensor drivers, vendor SDKs, and safety certifications are validated against one OS/ROS combination and re-validating is costly.
• Security patching — LTS distros keep receiving fixes long after a non-LTS release has gone quiet.
• Maintenance cost — fewer forced migrations means fewer engineering-hours spent chasing breaking changes instead of building the robot.

B.4Rolling Ridley

Rolling Ridley is structurally different from every other entry in the table above: it is not a fixed, dated release — it is a continuously updated development line that tracks the newest Ubuntu and the latest package versions as maintainers merge them.

Stable distribution (Jazzy, Lyrical, ...)
        ↓
fixed release, fixed lifecycle
        ↓
predictable, frozen APIs

Rolling Ridley
        ↓
continuously updated
        ↓
newest features, but breaking changes can land at any time

Rolling exists for package maintainers and Open Robotics itself: every future stable release (the next Lyrical-successor) is branched from Rolling at release time. It is where new features land first and get shaken out before being frozen into a named distribution.

B.5Humble vs. Jazzy vs. Kilted vs. Lyrical

Rather than a vague "newer is better," here is what actually changed release to release, limited to points that are officially documented:

B.6Introducing ROS 2 Lyrical Luth

Lyrical Luth is the 12th official ROS 2 distribution, released in May 2026, and is an LTS release supported until roughly May 2031. It follows Kilted Kaiju (non-LTS) and, like Jazzy before it, pairs with the current Ubuntu LTS — Ubuntu 26.04.

Changes that are specifically attributable to Lyrical (not inherited from Kilted or earlier):

• EventsCBGExecutor — a new callback-group-aware events executor, reported to reduce CPU usage versus the classic single-threaded/multi-threaded executors.
• rclpy AsyncNode — native asyncio integration for writing ROS 2 callbacks as Python coroutines.
• Zero-copy buffers for byte arrays — uint8[] message fields now use a rosidl::Buffer<uint8_t> type, enabling zero-copy transfer (currently limited to rmw_fastrtps_cpp).
• YAML type-tag support in ROS 2 parameter files, and per-message log severity levels in launch files.
• Remote rosbag2 recording control via ROS services, and Fish shell support for the CLI.

For most robotics teams, Lyrical's practical significance is simpler than any single feature: it is the first LTS after Jazzy, meaning it is the release you plan a five-year deployment lifecycle around if you're starting a new robot today and Jazzy's Ubuntu 24.04 base doesn't already fit your hardware constraints.

B.7Ubuntu and platform compatibility

Ubuntu
│
├── 20.04 → ROS 2 Foxy       (EOL)
├── 22.04 → ROS 2 Humble     (LTS, supported)
├── 24.04 → ROS 2 Jazzy / Kilted
└── 26.04 → ROS 2 Lyrical    (LTS, current)

Each ROS 2 distro binds to one primary Ubuntu LTS because the ROS packages are built against that Ubuntu release's exact GCC, CMake, Python, and system-library versions. Installing "the wrong" ROS distro's .deb packages on a mismatched Ubuntu version will fail to resolve dependencies — it is not a supported combination even where it might technically be coerced to work with a source build.

Ubuntu compatibility cascades into everything downstream: the Python interpreter version, the GCC/CMake toolchain, system libraries like Boost and OpenSSL, the DDS implementation packages, and — critically for robotics — which Gazebo release is packaged and tested against your ROS distro.

B.8Installing ROS 2 Lyrical

Check your system first

lsb_release -a
uname -a

Confirm you are on the Tier 1 platform (Ubuntu 26.04, amd64 or arm64) before proceeding — installing on a mismatched Ubuntu version is the single most common source of broken ROS 2 installs.

Locale

locale  # check for UTF-8

sudo apt update && sudo apt install locales
sudo locale-gen en_US en_US.UTF-8
sudo update-locale LC_ALL=en_US.UTF-8 LANG=en_US.UTF-8
export LANG=en_US.UTF-8

Enable the ROS 2 apt repository

sudo apt install software-properties-common
sudo add-apt-repository universe

sudo apt update && sudo apt install curl -y
export ROS_APT_SOURCE_VERSION=$(curl -s https://api.github.com/repos/ros-infrastructure/ros-apt-source/releases/latest | grep -F "tag_name" | awk -F\" '{print $4}')
curl -L -o /tmp/ros2-apt-source.deb "https://github.com/ros-infrastructure/ros-apt-source/releases/download/${ROS_APT_SOURCE_VERSION}/ros2-apt-source_${ROS_APT_SOURCE_VERSION}.$(. /etc/os-release && echo $VERSION_CODENAME)_all.deb"
sudo apt install /tmp/ros2-apt-source.deb

This is the current (post-Humble) way ROS 2 registers its apt source — it replaced the older manual apt-key + sources.list.d steps you may see in outdated tutorials.

Install

sudo apt update
sudo apt upgrade

sudo apt install ros-lyrical-desktop

sudo apt install ros-lyrical-ros-base

B.9Environment setup and sourcing

source /opt/ros/lyrical/setup.bash

Sourcing this script sets the environment variables and shell functions ROS 2 needs to find packages, executables, and message definitions. Without it, commands like ros2 won't exist in your shell at all.

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

Check what got set:

printenv | grep ROS

ROS_DISTRO=lyrical
ROS_VERSION=2
ROS_DOMAIN_ID=0
ROS_LOCALHOST_ONLY=0

B.10Verifying the installation

Terminal 1:

ros2 run demo_nodes_cpp talker

Terminal 2:

ros2 run demo_nodes_py listener

Talker Node
     │
     │ /chatter
     ▼
Listener Node

The talker publishes an incrementing string on /chatter; the listener subscribes and prints what it receives. If both terminals show matching output, your install, your DDS discovery, and your ROS_DOMAIN_ID are all working correctly together.

B.11Essential ROS 2 CLI commands

ros2 doctor

B.12Workspaces, colcon, and rosdep

ros2_ws/
│
├── src/       ← your source packages
├── build/     ← intermediate build artifacts
├── install/   ← what you actually source
└── log/       ← build/test logs

mkdir -p ~/ros2_ws/src
cd ~/ros2_ws
colcon build
source install/setup.bash

sudo rosdep init
rosdep update
rosdep install --from-paths src --ignore-src -r -y

B.13Creating your first package

# Python package
ros2 pkg create --build-type ament_python my_robot_pkg

# C++ package
ros2 pkg create --build-type ament_cmake my_robot_cpp

ament_python packages are built with setup.py/setup.cfg and pure Python; ament_cmake packages use CMakeLists.txt and compile C++ sources. A package can also mix both when it needs C++ performance-critical nodes alongside Python tooling.

B.14DDS, RMW, ROS_DOMAIN_ID, and QoS

ROS 2 API
    │
rclcpp / rclpy
    │
   rcl
    │
   RMW  (ROS middleware interface)
    │
DDS implementation (Fast DDS / Cyclone DDS / Zenoh / ...)
    │
 Network

The RMW layer lets ROS 2 swap DDS/middleware implementations without changing application code. Check the active one with:

echo $RMW_IMPLEMENTATION

Only change the middleware implementation for a concrete engineering reason — e.g. Zenoh for constrained or lossy links, or a specific vendor's Connext for a certified deployment — never as a default habit.

export ROS_DOMAIN_ID=10

Robot A, ROS_DOMAIN_ID=10 ─┐
                            ├─ can discover each other
Robot B, ROS_DOMAIN_ID=10 ─┘

Robot C, ROS_DOMAIN_ID=20  ─ isolated

QoS (Quality of Service) exists because one policy doesn't fit every topic:

• Camera stream / LiDAR — best-effort, small history depth: dropping an old frame is fine, latency matters more than guaranteed delivery.
• Motor command / emergency stop — reliable, low latency: dropped commands are unacceptable.
• Map — reliable, transient-local durability: a late-joining node should still receive the last published map.

B.15Debugging the ROS graph and rosbag2

Practical workflow for "the motors aren't moving":

1. Is the navigation node alive?      → ros2 node list
2. Does /cmd_vel exist?               → ros2 topic list
3. Is /cmd_vel actually publishing?   → ros2 topic hz /cmd_vel
4. What does it contain?              → ros2 topic echo /cmd_vel
5. Is the controller subscribed?      → ros2 topic info /cmd_vel
6. Are message types compatible?      → ros2 topic info /cmd_vel --verbose
7. Are QoS profiles compatible?       → ros2 topic info /cmd_vel --verbose

Record and replay real robot data for offline debugging:

ros2 bag record /scan /odom /cmd_vel
ros2 bag play my_bag
ros2 bag info my_bag

B.16Nav2, ros2_control, Gazebo, and MoveIt 2 on Lyrical

Sensors → Localization → Global Planner → Local Planner/Controller → /cmd_vel → Robot

Nav2 and ros2_control are both released per-distro alongside ROS 2 core and follow the same Ubuntu/ROS pairing — install them as ros-lyrical-navigation2 and ros-lyrical-ros2-control once your apt source is configured.

Controller Manager
      │
      ├── Joint State Broadcaster
      ├── Diff Drive Controller
      └── Other Controllers
              │
              ▼
       Hardware Interface
              │
              ▼
        Motor Drivers

Gazebo pairing follows the table in section B.5: Lyrical is packaged against Gazebo Jetty. Do not follow Gazebo Classic tutorials (gazebo_ros_pkgs) on Lyrical — that lineage is discontinued; the current integration path is the ros_gz bridge packages.

Robot Arm → MoveIt 2 → Motion Planning → ros2_control → Joint Controllers

You need MoveIt 2 when you're planning collision-aware motion for a manipulator; you don't need it for a mobile base that only needs Nav2's 2D planning.

B.17Migrating from Humble, Jazzy, or Kilted

Before moving a package from an older distro to Lyrical:

• Re-run rosdep install against the new Ubuntu base — package names and available versions shift with each Ubuntu LTS.
• Rebuild against Lyrical's toolchain rather than assuming an older binary will link — ABI compatibility across distros is not guaranteed.
• Check your package's upstream repository for a distro-specific branch or release (e.g. a jazzy vs. a lyrical branch) — many community packages maintain these separately.
• Re-test Gazebo/Nav2/ros2_control launch files — plugin names and default parameters can change between the Gazebo releases each distro pairs with.
• Read the "Migration" page under docs.ros.org/en/lyrical/Releases for the authoritative list — this appendix is a map, not a replacement for it.

B.18Jetson, Raspberry Pi, and Docker

NVIDIA Jetson boards ship a specific JetPack/Ubuntu/CUDA combination determined by NVIDIA, which is frequently a version or more behind the newest desktop Ubuntu LTS. Before targeting Lyrical (Ubuntu 26.04) on Jetson hardware, verify NVIDIA's current JetPack base OS — if it hasn't caught up yet, your practical choices are a containerized ROS 2 install (a Lyrical container on an older JetPack host OS), a source build, or staying on the ROS distro that matches your JetPack's actual Ubuntu base.

Native supported install   → JetPack's Ubuntu base matches a released ROS distro
Containerized ROS          → run a newer distro's container on an older host OS
Source build               → build ROS 2 from source against your exact JetPack image
Unsupported workaround     → forcing package installs across mismatched versions

Raspberry Pi (4/5) with a 64-bit Ubuntu Server or Desktop image gets Tier 1/Tier 3 ARM64 binaries depending on the distro — prefer 64-bit over 32-bit for any current ROS 2 work, since 32-bit support has been dropped across the ecosystem.

Ubuntu Host
│
├── ROS Container
│    ├── Nav2
│    ├── Perception
│    └── Application nodes
│
└── Hardware / drivers

Docker gives reproducible dependency isolation and easy deployment, at the cost of extra complexity around DDS discovery across container network boundaries and GPU passthrough for perception workloads.

B.19How to choose a ROS 2 distribution

Starting a new robot?
        │
        ▼
Need long-term production support?
        │
        ├── Yes → newest LTS compatible with your hardware/OS/driver stack
        │
        └── No
             │
             ▼
     Need newest ROS capabilities?
             │
             ├── Stable non-LTS release for early access with real support
             └── Rolling only if you're a maintainer or doing pure research

B.20Common mistakes and a cheat sheet

Cheat sheet

# Environment
source /opt/ros/lyrical/setup.bash
printenv | grep ROS

# Nodes / Topics / Services / Actions
ros2 node list
ros2 topic list  |  echo  |  info  |  hz
ros2 service list  |  call
ros2 action list  |  send_goal

# Parameters
ros2 param list  |  get  |  set

# Packages & build
ros2 pkg create --build-type ament_python 
colcon build --symlink-install
source install/setup.bash

# Dependencies
rosdep update
rosdep install --from-paths src --ignore-src -r -y

# Diagnostics & recording
ros2 doctor
ros2 bag record / play / info

📖Glossary

Distribution / distro

A versioned, tested set of compatible ROS 2 packages tied to a specific OS/toolchain.

LTS

Long Term Support — roughly five years of patches, versus about eighteen months for a non-LTS release.

Rolling Ridley

The continuously updated development line every future stable distro branches from.

RMW

ROS Middleware interface — the abstraction layer that lets ROS 2 swap DDS implementations.

DDS

Data Distribution Service — the pub/sub networking standard ROS 2's default transport is built on.

QoS

Quality of Service — per-topic policies (reliability, durability, history) tuned to what that data actually needs.

Overlay / underlay

Underlay = the base ROS install; overlay = your workspace, sourced on top of it.

Tier 1/2/3 support

Open Robotics' guarantee levels for a given OS/architecture combination, from fully tested down to best-effort.