Overlaying ROS Workspaces

Written by Marco Arruda


One of the critical topics of ROS, overlaying workspaces, something that can be confusing even for those who are working with ROS for some time. In this post, we are going to clarify why it happens and how to manage it.


ROSDS Initial environment

As usual, we are going to work with ROSDS, the ROS Development Studio. Creating a new ROSJect, you will have 2 workspaces in your environment, from scratch. One more designed to store ROSDS public simulations and ROS pre-installed packages. Let check this out!

Open a web shell and type the following command:

user:~$ echo $ROS_PACKAGE_PATH

You must see something like:


The workspaces are separated by “:”, let’s check one by one, following the order (which is very important!)

  1. /home/user/catkin_ws/src
  2. /home/user/simulation_ws/src
  3. /home/simulations/public_sim_ws/src
  4. /opt/ros/kinetic/share

The order was pre-defined by TheConstruct engineers team, to make it suitable for working with public simulations and custom simulations from the user. The order means:

ROS commands are going to look for packages starting from the workspace /home/user/catkin_ws/src, then /home/user/simulation_ws/src and so on. Remember, you can NOT have packages with the same name in the same workspace. But you can have packages with the same name in different workspaces! If the same package exists in two or more workspaces, the first one will be used.

So, if you want to overwrite a simulation from /home/simulations/public_sim_ws/src, you can do just creating/cloning the package with the same name at /home/user/simulation_ws/src.


Re-defining the $ROS_PACKAGE_PATH

“What if I want to add a new workspace to $ROS_PACKAGE_PATH?

This is an ENVIRONMENT VARIABLE, so is it just a matter of export it the way I want? WRONG!

The ENVIRONMENT VARIABLE is generated by the devel/setup.bash file from each workspace. It means this is just one of the results of sourcing a workspace!

If you need to re-define your $ROS_PACKAGE_PATH, you need to it in a safe/correct way, let’s call it. It is like described below:

  1. Source the installation path of ROS:
  2. Recompile the workspace you want just after the installation folder:
  3. Source its setup.bash:

At this moment, your $ROS_PACKAGE_PATH must be:


You only have 1 workspace defined.


Re-defining the $ROS_PACKAGE_PATH – Practical example

Let’s try it in ROSDS. First, I will create a new workspace:

user:~$ mkdir -p my_ros_workspace/src
user:~$ cd my_ros_workspace/src
user:~/my_ros_workspace/src$ catkin_init_workspace
user:~/my_ros_workspace/src$ cd ..
user:~/my_ros_workspace$ source /opt/ros/kinetic/setup.bash
user:~/my_ros_workspace$ catkin_make

Let’s source the devel/setup.bash of the new workspace and check our $ROS_PACKAGE_PATH:

user:~/my_ros_workspace$ source devel/setup.bash
user:~/my_ros_workspace$ echo $ROS_PACKAGE_PATH

And the result must be:


Even though we have many other workspaces defined, our $ROS_PACKAGE_PATH considers only one workspace! That’s because we have sourced just this workspace’s devel/setup.bash.


Overlaying workspaces

Now, let’s do some more advanced. We want to have more workspaces in our $ROS_PACKAGE_PATH. But let’s check something before:

Execute the following:

user:~$ source catkin_ws/devel/setup.bash
user:~$ echo $ROS_PACKAGE_PATH

You must see:


You still have the previous $ROS_PACKAGE_PATH defined, but only for the catkin_ws. The conclusion is each workspace has its own $ROS_PACKAGE_PATH defined.

Now, we are going to add public_sim_ws to our new workspace. This is the way to make the public simulations provided by TheConstruct available for your new workspace.

user:~$ source /home/simulations/public_sim_ws/devel/setup.bash
user:~$ echo $ROS_PACKAGE_PATH

You must have:


It means ROS is only considering the public_sim_ws. Let’s put our new workspace on top of it.

user:~$ cd my_ros_workspace/
user:~/my_ros_workspace$ rm -rf build devel
user:~/my_ros_workspace$ catkin_make
user:~/my_ros_workspace$ source devel/setup.bash

And you must have a completely new $ROS_PACKAGE_PATH



This is how you can work with multiple workspaces. Bare in mind ROS creates rules to give priority, but you are the one in charge of configuring the order of your workspaces!

Don’t forget to check the official reference: http://wiki.ros.org/catkin/Tutorials/workspace_overlaying

And if you like this kind of post, don’t forget to share it.

Leave a comment for us to know your personal feedback!


You May Also Like…



ROS & Robotics Curriculum Designed for Remote Teaching

Ready for your Robotics career?

Create an account, and start learning and developing robots

Share This