Hello ROS Developers

Welcome to this new post about ROS. In today’s post, we are going to learn what is the ROS_PACKAGE_PATH variable and how it is used by the ROS ecosystem.

The commands used here can be executed in your own computer if you have ROS installed, but for simplicity, we are going to use Robot Ignite Academy.

Before we start, if you are new to ROS, I highly recommend you taking the following course:

• ROS Basics In 5 Days (Python)

Ok, let’s get started, shall we?

In a computer with ROS installed, we have many variables with the ROS_ prefix. If we run env | grep ROS , for example, we may have something like the output below:

ROS_ROOT=/opt/ros/kinetic/share/ros
ROS_PACKAGE_PATH=/home/user/catkin_ws/src:/home/simulations/public_sim_ws/src:/opt/ros/kinetic/share
ROS_MASTER_URI=http://localhost:11311
ROS_VERSION=1
ROSLISP_PACKAGE_DIRECTORIES=/home/user/catkin_ws/devel/share/common-lisp:/home/simulations/public_sim_ws/devel/share/common-lisp
ROS_DISTRO=kinetic
ROS_ETC_DIR=/opt/ros/kinetic/etc/ros

Among these variables we can find the one we are looking for: ROS_PACKAGE_PATH

This variable is used by ROS in order to find ROS Packages. To better understand this, let’s consider the command below, used to control robots using the keyboard:

roslaunch turtlebot_teleop keyboard_teleop.launch

The first parameter of the roslaunch  command is the package name, which in this case is turtlebot_teleop .

When we run the command exemplified above, in order to find the turtlebot_teleop  package, ROS will look for the ROS_PACKAGE_PATH variable.

If we run roscd turtlebot_teleop to enter on the that package, for instance, on Robot Ignite Academy the package is located at /home/simulations/public_sim_ws/src/all/turtlebot/turtlebot_teleop  as can be seen below:

user:~$ roscd turtlebot_teleop
user:/home/simulations/public_sim_ws/src/all/turtlebot/turtlebot_teleop$ pwd
/home/simulations/public_sim_ws/src/all/turtlebot/turtlebot_teleop

If you look carefully, you can notice that the turtlebot_telop package is on the “Public Simulations Workspace”, which is /home/simulations/public_sim_ws/src. Now, with a closer look at the ROS_PACKAGE_PATH variable, we can find that path on it:

ROS_PACKAGE_PATH=/home/user/catkin_ws/src:/home/simulations/public_sim_ws/src:/opt/ros/kinetic/share

So, the turtlebot_teleop package only was found because its workspace path is set on ROS_PACKAGE_PATH.

If we unset that variable and try to roscd on that package again, it is not going to work, as can be seen with the commands  unset ROS_PACKAGE_PATH and roscd turtlebot_teleop.

user:~$ cd
user:~$ unset ROS_PACKAGE_PATH
user:~$ roscd turtlebot_teleop
roscd: No such package/stack 'turtlebot_teleop'

Here we can see that ROS wasn’t able to find the package. If we look at the ROS_ prefixed environment variables again, we won’t find ROS_PACKAGE_PATH:

user:~$ env | grep ROS
ROS_ROOT=/opt/ros/kinetic/share/ros
ROS_MASTER_URI=http://localhost:11311
ROS_VERSION=1
ROSLISP_PACKAGE_DIRECTORIES=/home/user/catkin_ws/devel/share/common-lisp:/home/simulations/public_sim_ws/devel/share/common-lisp
ROS_DISTRO=kinetic
ROS_ETC_DIR=/opt/ros/kinetic/etc/ros

If we source our catkin_ws again with source ~/catkin_ws/devel/setup.bash, the variable will be exported and ROS  will be able to find the package again:

user:~$ source ~/catkin_ws/devel/setup.bash
user:~$ roscd turtlebot_teleop
user:/home/simulations/public_sim_ws/src/all/turtlebot/turtlebot_teleop$

Creating a package in an unexpected location

Now let’s go a bit further and create a package in a place that nobody would do it. We are going to create it in the /tmp folder, just to let you better understand the importance of ROS_PACKAGE_PATH.

We can use the cd /tmp/  and catkin_create_pkg tutorial_package  commands to achieve that:

user:~$ cd /tmp/
user:/tmp$ catkin_create_pkg tutorial_package
Created file tutorial_package/package.xml
Created file tutorial_package/CMakeLists.txt
Successfully created files in /tmp/tutorial_package. Please adjust the values in package.xml.

We can clearly see that the package was created in /tmp/tutorial_package, but if we try to navigate to it using roscd tutorial_package, ROS won’t be able to find it:

user:/tmp$ roscd tutorial_package
roscd: No such package/stack 'tutorial_package'

That happens because the /tmp folder is not on the ROS_PACKAGE_PATH variable. We can easily add it using the next command:

export ROS_PACKAGE_PATH=/tmp:$ROS_PACKAGE_PATH

Now if we check the value of the variable with env | grep ROS_P , we can find /tmp there:

user:/tmp$ export ROS_PACKAGE_PATH=/tmp:$ROS_PACKAGE_PATH
user:/tmp$ env | grep ROS_P
ROS_PACKAGE_PATH=/tmp:/home/user/catkin_ws/src:/home/simulations/public_sim_ws/src:/opt/ros/kinetic/share

If we try to enter our package with roscd tutorial_package again, ROS will find it:

user:/tmp$ roscd tutorial_package
user:/tmp/tutorial_package$ pwd
/tmp/tutorial_package

So easy to understand the ROS_PACKAGE_PATH variable, isn’t it?

Remember that we also have a video version of this post on YouTube:

I hope you liked the post (and the video), if that is the case, please consider subscribing to our channel on YouTube. Additionally, should you have any questions or suggestions, please leave your comment on the comments section of the video.

Keep pushing your ROS Learning.