Moving from ROS 2 Humble to Lyrical Luth: An Upgrade Checklist for Production Systems

ROS 2 Humble Hawksbill reaches end-of-life in May 2027, according to the official distribution table. The current long-term support release, Lyrical Luth, came out on 22 May 2026 and is supported until May 2031. Moving straight from Humble to Lyrical crosses Iron, Jazzy and Kilted, and each of those releases removed or renamed something. A phased approach of audit, port, then validate keeps a production upgrade predictable.

This checklist is written for teams that maintain ROS 2 robots under a service contract: system integrators, automation suppliers and university labs running shared research platforms. Every change listed is taken from the release notes and guides in the ROS 2 documentation (Lyrical branch), which you can search in the ROS 2 documentation base.

Why the calendar should drive the plan

From the date of this article (5 October 2026) to Humble's end-of-life in May 2027 is roughly seven months. The Lyrical release timeline spells out what end-of-life means: the distribution stops receiving updates, including security updates. For a robot sold into a factory or a hospital, that is hard to justify.

• Kilted Kaiju (released 23 May 2025) ends in December 2026, so it is not worth targeting.
• Jazzy Jalisco (released 23 May 2024) is supported until May 2029.
• Lyrical Luth (released 22 May 2026) is supported until May 2031.
• Makoa Mata-mata, planned for May 2027, is described as a regular release supported until December 2028.

Phase 1: audit what you are running

Start with an inventory. Three findings usually shape the rest of the project.

Operating system

Humble's Tier 1 platform was Ubuntu 22.04 (Jammy). Lyrical's Tier 1 platforms are Ubuntu Resolute (26.04) on amd64 and arm64 and Windows 11 (VS2022) on amd64. RHEL 10 is Tier 2. Ubuntu Noble (24.04) and Debian Trixie are only Tier 3, with early EOLs (Noble on 2029-06-01, Trixie on 2028-08-09), and Tier 3 means building Lyrical from source. Lyrical's minimum language requirements are C++20, C17 and Python 3.12 to 3.14.

Middleware

The default remains rmw_fastrtps_cpp. In Lyrical, Fast DDS, Cyclone DDS and Zenoh are Tier 1 on all architectures. Connext is Tier 1 on all architectures except arm64. If you use Fast DDS XML profiles, note that Kilted renamed fastrtps to fastdds. The rmw names stay the same, but the XML profile environment strings change.

Environment variables

Search your launch scripts and service files for ROS_LOCALHOST_ONLY. Iron deprecated it in favour of ROS_AUTOMATIC_DISCOVERY_RANGE (SUBNET by default, or LOCALHOST, OFF and SYSTEM_DEFAULT) together with ROS_STATIC_PEERS, a semicolon-separated list of addresses.

Phase 2: port the code

The CMake change catches people out. The Kilted deprecation warning proposes a target_link_libraries() call with a scope keyword such as PUBLIC. If the same target already uses the plain form, which some ament_cmake macros like ament_add_gtest do internally, remove the keyword. Otherwise CMake reports that all uses must be either all-keyword or all-plain.

In Python, Jazzy changed rclpy.node.Node.declare_parameter so that it no longer allows statically typing a parameter without a default value. Check any node that declares parameters this way.

Phase 3: validate behaviour, not just the build

Several changes compile cleanly but alter how the system runs. Add these to your acceptance tests:

1. Executor threading: since Iron, the multi-threaded executor defaults to the number of CPUs on the machine, or 2 if the OS cannot report it.
2. Callback ordering: since Jazzy, callbacks in the default executors are no longer ordered consistently, even within the same entity.
3. Logging: since Iron, the spdlog backend flushes on each error message and every five seconds.
4. Bags: since Iron, rosbag2 writes mcap by default. sqlite3 remains selectable and both formats play back.
5. Environment check: printenv | grep -i ROS should show ROS_DISTRO=lyrical, and ros2 doctor --report now also lists actions, services and ROS environment variables.
6. QoS on services: if clients stop getting responses after the upgrade, ros2 service info --verbose (new in Lyrical) prints the QoS profile of each request reader and response writer, much as ros2 topic info --verbose does for topics.
7. Recorded data: replay a few representative bags from the Humble system through the upgraded nodes. Jazzy changed how offered_qos_profiles are represented in bag metadata and override files, which now use human-readable values.

For a production system it also helps to pin exactly what was tested. The documentation describes apt snapshots for long-term support releases on Ubuntu. These let you install packages as they were in the main repository at the time of the snapshot, for example with sudo apt install ros-lyrical-desktop once the snapshot source is configured. The docs warn that the ROSDISTRO_INDEX_URL environment variable takes precedence over the ~/.config/rosdistro/config.yaml pin, so unset it if it is defined. They also note that moving an existing installation onto a snapshot with sudo apt dist-upgrade may downgrade packages. Two further warnings matter for maintenance contracts. Snapshots receive no bug fixes or security updates. And when a distribution reaches end-of-life, a last snapshot named final is taken, which will be the frozen state of Humble after May 2027.

What to put in the handover note

• The ROS distribution and Ubuntu release on every machine, with the RMW implementation in use.
• The discovery settings (ROS_DOMAIN_ID, ROS_AUTOMATIC_DISCOVERY_RANGE, ROS_STATIC_PEERS) for each site.
• Any QoS overrides used for recording, since mcap is now the default bag format.
• The executor chosen for each node, if you move to the Lyrical EventsCBGExecutor, which the release notes say uses 10% to 15% less CPU than the single- and multi-threaded executors.

Leftovers from earlier ROS 1 ports

Codebases that started life in ROS 1 often carry old build metadata, and an LTS upgrade is a good moment to clean it up. ROS 2 requires package.xml format 2 or higher, and colcon follows REP 149, with format 2 also supported. The run_depend tag is no longer allowed. Replace it with exec_depend if the dependency is needed at run time, and/or build_export_depend if packages that build against yours need it. Use both if unsure. When build_depend, build_export_depend and exec_depend all name the same package, a single depend tag replaces them.

Remember also that a colcon workspace creates build, install and log directories next to src, and that, compared to catkin, there is no devel directory. Scripts that still look for devel/setup.bash will fail silently on the new build server.

Integrators who maintain their own upgrade runbooks can also publish them as a private base from the knowledge base builder. The ROS 2 base covers the core documentation only, so check third-party packages such as Nav2 or MoveIt 2 against their own release notes.