ROS2-010-Communication Mechanisms, Wrapping Up: Duplicate Package Names and the Workspace Overlay Mechanism

Introduction

When you write packages in ROS2, you generally write and build them inside a single workspace. But when a programmer needs to write different packages across several workspaces, it is quite possible to end up giving different packages the same name in different workspaces. Say you create a package called "C" in both workspace A and workspace B, and suppose each of those packages has a "C_node" node — then when we open a new terminal and just run

ros2 run C C_node

which workspace's package runs?

The workspace overlay mechanism

In ROS2, when a package with the same name exists in different workspaces, what ros2 run C C_node actually does depends on ROS2's workspace overlay mechanism. That mechanism has two parts:

1. When ROS2 tries to find a package, it searches via an environment variable, AMENT_PREFIX_PATH (both C++ and Python use AMENT_PREFIX_PATH, though Python also relies on PYTHONPATH). That variable records the paths of the various workspaces, and the order of the paths decides their priority — paths added later get searched first.
2. When you run . install/setup.bash inside a particular workspace, or run source <path to that workspace>/install/setup.bash from anywhere, that workspace's path gets recorded and put at the front of AMENT_PREFIX_PATH.

So when you have packages with the same name in different workspaces, whether that package runs depends on the order in which you source the different workspaces:

• If you only activated one of workspace A or B in the terminal, ROS2 can only find packages in the activated workspace, and in that case it will unambiguously run the matching package.

• If you source both workspaces in order:

  • If you source A first and B second, then because B's path sits further forward in AMENT_PREFIX_PATH, workspace B's package takes effect.
  • If you source B first and A second: because A's path sits further forward in AMENT_PREFIX_PATH, workspace A's package takes effect.

What can duplicate package names be used for?

They can confuse you even more. So the advice is: don't do it😅

Or you could...

When naming different packages, you could try the "<workspace>-<package name>" style, which makes duplicate names across workspaces very unlikely☝🤓

Important

This article was translated by Hermes Agent; the original text can be found at here. The translation is for reference only. Translation time: 2026-11-05