As the number of ROS packages increases, it is hard to quickly find a package
and guess its functionality based on its name.
Over time, the lack of naming conventions created problems like use of
unexplained acronyms or packages with the same functionality but different names.
For now, ROS package names translate directly to packages in supported Operating
Systems: therefore, there is a flat global namespace in which rules have to
This REP proposes rules to name a ROS package properly.
Some of those rules are mandatory, others merely advised.
By habit, a package name is often used as a namespace (in C++ or any other language).
Thus, the naming rules have to be strict.
- alphanumerics are a-z0-9 only
- alphabetics are a-z only
For clarity these are both specifically exclusively lowercase.
A name must:
- only consist of lowercase alphanumerics and _ separators and start with an alphabetic character.
This allows it to be used in generated symbols and functions in all supported languages.
Lowercase is required because the names are used in directories and filenames and some
platforms do not have case sensitive filesystems.
- not use multiple _ separators consecutively.
This allows generated symbols to use the __ separator to guarenteed the avoidance
of collisions with symbols from other packages, for example in the message generators.
- be at least two characters long.
This rule is simply to force the name of the package to be more human understandable.
It's recommended to be noteably longer, see below.
- Package names should be specific enough to identify what the package does.
For example, a motion planner should not be called planner.
If it implements the wavefront propagation algorithm, it might be called
There's obviously tension between making a name specific and keeping it from becoming
- Using catchall names such as utils should be avoided. They do not scope what goes
into the package or what should be outside the package
- A package name should not contain ros as it is redundant.
Exceptions include core packages and ROS bindings of an upstream library
- The package name should describe what the package does, not where it came from.
One of ROS's goals is to develop a canonical set of tools for making robots do
Then again, as stated in the rules below, if a package is specialized
by an entity (lab, company, ...), prepend the name of the entity.
But once the package is commonly used, owned and maintained, that name can be dropped
as the package becomes the reference
- Do not use a name that's already been taken.
To check whether a name is taken, consult . If you'd like your
repository included in that list, see the tutorial at
The following rules define the different parts of the package name.
The overall idea is to prepend a name with words that distinguish it from similar
functional implementation (e.g.: lab, robot) but in order of importance
Similarly, words that specialize this functionality are appended
(e.g. msgs, config ...).
The rules to add those words should be followed in order.
- if a package is specialized for a software project, prepend its name
- if a package is specialized for a hardware piece, prepend its name
- if a package is specialized for a robot, prepend its name
- if a package is specialized by an entity (lab, company, ...), prepend the
name of the entity.
Once the package is commonly used, owned and maintained, that name can be dropped
- if a package is a driver, append driver
- if a package contains any of a ROS message/service/action, append msgs
- if a package is a plugin for a library, append <library_name>_plugins, e.g.
- a meta package for a robot should be named <name_of_the_robot>_robot, e.g.
- a package containing the URDF and meshes of a robot should be named
<name_of_the_robot>_description, e.g pr2_description
- if a package is meant for test only, append tests
- a package containing only a set of launch files should end with launch
- a package containing only a set of launch files whose goal is to start a robot
should end with bringup
- a package containing one or more tutorials only should end with tutorials.
If it is a set of tutorials for another package, it should contain that other
package name: e.g. navigation and navigation_tutorials
- a package containing one or more demos only should end with demos
- third party libraries that are patched / integrated into ROS should not be named
like their rosdep key as it creates a conflict across Ubuntu versions.
If it is not specialized, name it generically <name_of_library>_ros
The following is a list of examples following the above rules:
- A set of launch files for a wavefront planner, made for the PR2 by
Willow Garage would have the following names when specializing the package more and more:
- OpenCV 3 package, packaged for ROS: `opencv3_ros`
- a set of launch files for navigation tests: `navigation_launch_tests`