You're reading the documentation for a development version. For the latest released 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.

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.