You're reading the documentation for an older, but still supported, version of ROS 2. For information on the latest version, please have a look at Humble.

Integrating launch files into ROS 2 packages

Goal: Add a launch file to a ROS 2 package

Tutorial level: Intermediate

Time: 10 minutes


You should have gone through the tutorial on how to create a ROS 2 package.

As always, don’t forget to source ROS 2 in every new terminal you open.


In the previous tutorial, we saw how to write a standalone launch file. This tutorial will show how to add a launch file to an existing package, and the conventions typically used.


1 Create a package

Create a workspace for the package to live in:

mkdir -p launch_ws/src
cd launch_ws/src
ros2 pkg create py_launch_example --build-type ament_python

2 Creating the structure to hold launch files

By convention, all launch files for a package are stored in the launch directory inside of the package. Make sure to create a launch directory at the top-level of the package you created above.

For Python packages, the directory containing your package should look like this:


In order for colcon to find the launch files, we need to inform Python’s setup tools of our launch files using the data_files parameter of setup.

Inside our file:

import os
from glob import glob
from setuptools import setup

package_name = 'py_launch_example'

    # Other parameters ...
        # ... Other data files
        # Include all launch files.
        (os.path.join('share', package_name), glob('launch/*launch.[pxy][yma]*'))

3 Writing the launch file

Inside your launch directory, create a new launch file called is recommended, but not required, as the file suffix for Python launch files. However, the launch file name needs to end with to be recognized and autocompleted by ros2 launch.

Your launch file should define the generate_launch_description() function which returns a launch.LaunchDescription() to be used by the ros2 launch verb.

import launch
import launch_ros.actions

def generate_launch_description():
    return launch.LaunchDescription([

4 Building and running the launch file

Go to the top-level of the workspace, and build it:

colcon build

After the colcon build has been successful and you’ve sourced the workspace, you should be able to run the launch file as follows:

ros2 launch py_launch_example


The launch documentation provides more details on concepts that are also used in launch_ros.

Additional documentation/examples of launch capabilities are forthcoming. See the source code ( and in the meantime.