Migrating a Production Robot From ROS 2 Humble to Jazzy: A Field Report

TL;DR: A ROS 2 Humble to Jazzy migration on a production mobile robot took Fictionlab’s team roughly two engineering weeks per platform, dominated by operating-system and toolchain changes, dependency updates, and Gazebo Classic removal. The safest path is a parallel workspace strategy: keep Humble as your golden image on Ubuntu 22.04, build Jazzy on Ubuntu 24.04 in a separate branch, and cut over only after nav stack and perception nodes pass the same field tests. Do not migrate drivers you plan to replace, prototypes with less than 12 months of remaining lifetime, or nodes locked to third-party SDKs that have not released Jazzy-compatible software.

Why a ROS 2 Humble to Jazzy Migration Is Not a One-Command Job

ROS 2 Humble Hawksbill is a long-term support release valid until May 2027. ROS 2 Jazzy Jalisco is the next LTS, supported until May 2029, and targets Ubuntu 24.04 Noble. On paper the ROS 2 Humble to Jazzy migration looks like a distro bump. In practice it forces you to move the operating system, the compiler toolchain (GCC 13), Python 3.12, and the simulator (Gazebo Classic is end-of-life, with Gazebo Harmonic being the usual supported replacement). Each of those layers can introduce compatibility changes that a mobile robot codebase will hit.

Fictionlab’s team ran this migration on the Leo Rover software stack and on internal Raph Rover builds used for field robotics research. This report documents what broke, how long the fixes took, and where the parallel-workspace approach saved rollback time.

What Breaks First: The Real List of Jazzy Changes for Mobile Robots

Before touching code, audit your stack against the changes that actually affect UGV platforms. The following items caused the most churn during the ROS 2 Humble to Jazzy migration:

• Ubuntu 24.04 requirement. Jazzy has no official Ubuntu 22.04 binary packages. You need a fresh image, virtual machine, or container.
• Python 3.12. Python dependencies and older packaging tools may need updates. Test Python packages, generated interfaces, and package metadata early rather than assuming a Humble Python environment will build unchanged.
• Gazebo Classic is gone. gazebo_ros_pkgs is not released for Jazzy. You migrate to Gazebo Harmonic via ros_gz, which changes plugin configuration, topic bridging, and often SDF files.
• Navigation2 API. Nav2 launch files, parameters, and behavior-tree plugins have changed across releases. Custom behavior tree XMLs from Humble may need edits and should be validated against the Jazzy Nav2 packages you deploy.
• rclcpp and dependency compatibility. Code using deprecated APIs, older QoS patterns, or assumptions about transitive includes may require updates. Treat compiler warnings and clean Jazzy builds as migration work rather than relying on Humble-era behavior.
• ament_cmake packaging. A clean rebuild can expose incomplete export declarations and missing dependencies that were previously hidden by an existing workspace overlay.
• tf2 include compatibility. Some packages need include updates for current tf2_geometry_msgs headers. The exact change depends on the APIs and headers used by the package.
• DDS and QoS validation. Fast DDS remains the default RMW implementation in standard ROS 2 installations, but multi-machine deployments should be retested for discovery, network configuration, and QoS compatibility.

None of these are catastrophic in isolation. The cost is cumulative: a stack with 40 to 60 in-house packages plus third-party drivers typically hits multiple compatibility issues.

How to Set Up a Parallel Workspace Strategy

The single most useful decision during this ROS 2 Humble to Jazzy migration was to never overwrite the working Humble system. Fictionlab’s team kept the production robot on Humble/22.04 and provisioned a second SD card image with Jazzy/24.04. Both workspaces built from the same Git repository, on separate branches.

The layout on the developer machine looked like this:

• ~/ros2_humble_ws – sourced from /opt/ros/humble/setup.bash, branch main.
• ~/ros2_jazzy_ws – sourced from /opt/ros/jazzy/setup.bash inside a 24.04 container, branch migration/jazzy.

To avoid environment leakage, wrap each in a shell function rather than sourcing globally in .bashrc. Define and use each function only in the environment where its ROS distribution is installed. A minimal example:

Add to the relevant .bashrc:

• humble() { source /opt/ros/humble/setup.bash && source ~/ros2_humble_ws/install/setup.bash; }
• jazzy() { source /opt/ros/jazzy/setup.bash && source ~/ros2_jazzy_ws/install/setup.bash; }

For the 24.04 environment, a Docker container is the fastest route if your development machine still runs 22.04:

docker run -it --rm --net=host --ipc=host -v $HOME/ros2_jazzy_ws:/ws ros:jazzy

Inside the container, install ros-jazzy-desktop, ros-jazzy-navigation2, ros-jazzy-ros-gz, and your driver dependencies, then build with colcon build --symlink-install. Keep both branches synchronized by rebasing migration/jazzy onto main weekly during the migration window.

What the Migration Actually Cost, Package by Package

Here are approximate times measured during Fictionlab’s internal migration sprint. Numbers are per package, single engineer, including build fixes and a basic runtime smoke test.

• Custom differential drive controller (rclcpp): approximately 2 hours. Mostly QoS and dependency compatibility updates.
• URDF and xacro description package: approximately 1 hour. Gazebo Classic plugin references and simulation configuration had to be replaced with Gazebo Sim-compatible systems and ros_gz bridging where needed.
• Nav2 configuration and behavior tree: approximately 6 hours. BT XML edits, parameter YAML re-validation, and one custom recovery node rewrite.
• Camera driver (third-party): blocked. Vendor had no Jazzy release. Solution: build from source against Jazzy, patch two headers. Approximately 4 hours plus ongoing maintenance risk.
• SLAM Toolbox integration: approximately 1 hour. Binary package worked out of the box.
• Gazebo Classic worlds and models: approximately 3 days to port two test worlds to Harmonic. This was the single largest line item.
• CI pipeline (GitHub Actions matrix): approximately 4 hours to add a Jazzy job alongside Humble.

Total for a stack of 18 in-house packages plus simulation assets: about 9 working days for the first platform, 4 days for the second because tooling and patches carried over.

When You Should Not Migrate

Not every project benefits from the ROS 2 Humble to Jazzy migration right now. Humble is supported until May 2027, which is enough runway for many deployments. Skip or defer migration when:

• Your robot ships to customers in the next 6 months. Freeze on Humble, migrate the next hardware revision.
• You depend on a driver with no Jazzy-compatible software and no source access. Wait for the vendor or budget for a replacement sensor.
• Your project ends before 2027. Research prototypes, thesis platforms, and short-cycle integrations rarely justify the migration cost.
• You rely heavily on Gazebo Classic worlds you cannot afford to port. Harmonic is the correct long-term choice, but the porting effort is real.

Migrate when you need Ubuntu 24.04 for other reasons, when your stack targets a 2027+ deployment, or when you want the Nav2 and MoveIt improvements available in the Jazzy ecosystem.

How to Validate the Migration Before Cutover

A clean build is not a successful migration. Fictionlab’s team uses a three-stage validation before declaring a Jazzy image production-ready:

1. Bench test. Robot on blocks, wheels free. Verify odometry, IMU, and camera topics publish at expected rates. Compare ros2 topic hz output against Humble baseline.
2. Closed-course test. Same waypoint mission run on Humble and Jazzy back-to-back. Log /tf, /odom, and Nav2 feedback. Diff the trajectories.
3. 24-hour soak. Idle the robot with all nodes running. Watch for memory growth, DDS discovery flaps, and log flooding. This catches most regressions that unit tests miss.

Only after all three pass on the same hardware does the Jazzy image replace Humble as the default. Even then, keep the Humble SD card image archived for at least one release cycle.

Frequently Asked Questions

Q: Can you run Humble and Jazzy nodes on the same network?

A: Yes, if both use compatible RMW implementations and matching QoS profiles, DDS can interoperate across ROS 2 distributions. However, nodes must use compatible interface definitions as well as compatible QoS; incompatible types or QoS settings can prevent communication. Treat cross-distro operation as a short-term migration aid, not a permanent architecture.

Q: Is Gazebo Harmonic mandatory, or can you keep Gazebo Classic on Jazzy?

A: Gazebo Classic has no supported Jazzy release. You can build it from source, but it is unmaintained upstream. For projects maintained beyond 2025, migrating simulation assets to Harmonic via ros_gz is the sustainable path.

Q: How long does a typical ROS 2 Humble to Jazzy migration take?

A: For a mobile robot with 15 to 25 in-house packages and standard Nav2 integration, budget 8 to 12 engineering days. Simulation asset porting can double that if you have complex custom worlds.

Q: What is the biggest hidden cost?

A: Third-party driver dependencies. If a vendor has not released Jazzy-compatible software, you are either patching source, replacing the sensor, or delaying migration. Audit this before you start.

Q: Should you migrate a research platform used for one-off experiments?

A: Usually no. If the project ends before Humble EOL in May 2027, the migration effort rarely returns value. Focus engineering time on the experiment itself.

Q: Does the Leo Rover ship with Humble or Jazzy?

A: Check the current documentation at docs.fictionlab.pl for the exact image shipping today. Fictionlab maintains both branches during the transition window.

Q: What about ROS 2 Kilted, released after Jazzy?

A: Kilted is a non-LTS release with a shorter support window. For production platforms, skipping non-LTS releases and moving Humble to Jazzy directly is often the lower-risk path.

Where to Go Next

The ROS 2 Humble to Jazzy migration is manageable when you plan for the OS jump, budget for simulation porting, and keep the old image bootable until Jazzy proves itself in the field. For teams running custom stacks on Leo Rover or Raph Rover, Fictionlab’s team maintains migration notes, tested Jazzy images, and driver patches in the official documentation. If you are building a research platform and want to discuss integration paths, see applications for research or custom robotics services.

For step-by-step setup instructions and current supported ROS 2 distributions on Fictionlab hardware, visit docs.fictionlab.pl.