[Documentation] [TitleIndex] [WordIndex


For this tutorial we will inspect a package in ros-tutorials, please install it using

$ sudo apt-get install ros-<distro>-ros-tutorials

Replace '<distro>' (including the '<>') with the name of your ROS distribution (e.g. hydro, groovy, electric, fuerte etc.)

Quick Overview of Filesystem Concepts

When you look at the filesystem, it's easy to tell packages and stacks apart:


Filesystem Tools

Code is spread across many ROS packages and stacks. Navigating with command-line tools such as ls and cd can be very tedious which is why ROS provides tools to help you.

Using rospack and rosstack

rospack and rosstack allow you to get information about packages and stacks. In this tutorial, we are only going to cover the find option, which returns the path to package or stack.


$ rospack find [package_name]
$ rosstack find [stack_name]


$ rospack find roscpp

Would return:

If, for example, you have used the binary install of ROS Fuerte on Ubuntu linux, you would see exactly:

Using roscd

roscd is part of the rosbash suite. It allows you to change directory (cd) directly to a package or a stack.


$ roscd [locationname[/subdir]]

Run this example:

$ roscd roscpp

To verify that we have changed to the roscpp package directory. Now let's print the working directory using the Unix command pwd:

$ pwd

You should see:

You can see that YOUR_INSTALL_PATH/share/roscpp is the same path that rospack find gave in the previous example.

Note that roscd, like other ROS tools, will only find ROS packages that are below the directories listed in your $ROS_PACKAGE_PATH. To see what is in your $ROS_PACKAGE_PATH, type:


If you have not modified your $ROS_PACKAGE_PATH, you should see:

Similarly to other environment paths, you can add additional directories to your $ROS_PACKAGE_PATH, with each path separated by a colon ':'

1. Subdirectories

roscd can also move to a subdirectory of a package or stack.


$ roscd roscpp/cmake
$ pwd

You should see:

Special cases for roscd

There are a few special places you can tell roscd to go, that are not a package or stack.

1. roscd with no arguments

roscd without an argument will take you to $ROS_WORKSPACE. Try:

$ roscd
$ pwd

You should see:

Note: Prior to Fuerte, roscd would take you to $ROS_ROOT.

2. roscd log

roscd log will take you to the folder where ROS stores log files. Note that if you have not run any ROS programs yet, this will yield an error saying that it does not yet exist.

If you have run some ROS program before, try:

$ roscd log

Using rosls

rosls is part of the rosbash suite. It allows you to ls directly in a package, stack, or common location by name rather than by package path.


$ rosls [locationname[/subdir]]


$ rosls roscpp_tutorials

Would return:

Tab Completion

It can get tedious to type out an entire package name. In the previous example, roscpp_tutorials is a fairly long name. Luckily, some ROS tools support TAB completion.

Start by typing:

$ roscd roscpp_tut<<< now push the TAB key >>>

After pushing the TAB key, the command line should fill out the rest.

This works because roscpp_tutorials is currently the only ROS package that starts with roscpp_tut.

Now try typing:

$ roscd tur<<< now push the TAB key >>>

After pushing the TAB key, the command line should fill out as much as possible:

However, in this case there are multiple packages that begin with turtle. Try typing TAB another time. This should display all the ROS packages that begin with turtle

On the command line you should still have

Now type a s after turtle and then push TAB

$ roscd turtles<<< now push the TAB key >>>

Since there is only one package that start with turtles, you should see:


You may have noticed a pattern with the naming of the ROS tools:

This naming pattern holds for many of the ROS tools.

2024-06-15 12:28