Getting Started with ROS 2 Python

ROS 2 (Robot Operating System 2) is an open-source middleware widely used for robotics development. It provides communication between different components (called nodes) and makes it easier to build scalable robotic systems.

This guide covers the basics of getting started with ROS 2 using Python, including installation, creating your first node, making it executable, and running it from the command line.

Installing ROS 2

The easiest way to install ROS 2 on Ubuntu is to follow the official installation guide provided by the ROS team.

Follow the instructions here:

https://docs.ros.org/en/jazzy/Installation/Ubuntu-Install-Debs.html

After the installation is complete, remember to source the ROS environment.

source /opt/ros/jazzy/setup.bash

To make this permanent every time you open a terminal, add it to your .bashrc.

echo "source /opt/ros/jazzy/setup.bash" >> ~/.bashrc
source ~/.bashrc

Creating Your First ROS 2 Python Node

A minimal ROS 2 Python node looks like this:

#!/usr/bin/env python3
 
import rclpy
from rclpy.node import Node
 
def main(args=None):
    rclpy.init(args=args)
 
    node = Node("py_test")
 
    node.get_logger().info("Hello World!")
 
    rclpy.spin(node)
 
    rclpy.shutdown()
 
if __name__ == "__main__":
    main()

When executed, the node prints:

[INFO] Hello World!

Why Use `rclpy.spin(node)`?

A common question from beginners is:

Why doesn't my ROS node stay alive?

Without:

rclpy.spin(node)

your program executes the code from top to bottom and immediately exits.

The spin() function keeps the node alive and allows ROS 2 to continue processing:

Subscribers
Timers
Services
Actions
Publishers
Incoming messages

Think of it as an event loop for your ROS node.

Without it:

Initialize
 
↓
 
Print Hello World
 
↓
 
Exit Program

With it:

Initialize
 
↓
 
Print Hello World
 
↓
 
Wait for ROS Events
 
↓
 
Shutdown

Only when the node is stopped (for example by pressing Ctrl + C) will execution continue to:

rclpy.shutdown()

which cleanly shuts down the ROS client library.

Making Your Node Executable

Instead of running Python files manually, ROS 2 allows nodes to be executed using:

ros2 run

To do this, you need to register your Python file inside the package's setup.py.

Open:

setup.py

Locate the entry_points section.

Suppose your project structure looks like this:

ros2_ws/
└── src/
    └── my_py_pkg/
        ├── setup.py
        └── my_py_pkg/
            └── my_first_node.py

If:

Package name is my_py_pkg
Python file is my_first_node.py
Function is main()
Executable name should be bebas

Then add the following line inside console_scripts:

entry_points={
    "console_scripts": [
        "bebas = my_py_pkg.my_first_node:main",
    ],
},

The format is always:

<executable-name> = <package>.<python-file>:<function>

For this example:

bebas
        │
        ▼
my_py_pkg.my_first_node:main

This tells ROS 2:

create an executable named bebas
execute the main() function
inside my_first_node.py

Build the Workspace

After updating setup.py, rebuild your workspace from the root directory.

cd ~/ros2_ws
 
colcon build

Once the build finishes, source the workspace.

source install/setup.bash

If you've added the workspace to your .bashrc, simply reload it.

source ~/.bashrc

This ensures your terminal recognizes newly added executables.

Running Your Node

Once the package has been built successfully, you can execute it using:

ros2 run <package-name> <executable-name>

For the previous example:

ros2 run my_py_pkg bebas

ROS 2 will locate the executable registered in setup.py and execute the corresponding Python function automatically.

Common Issues

Command Not Found

If ros2 cannot be found, make sure you've sourced ROS 2.

source /opt/ros/jazzy/setup.bash

Executable Not Found

If ros2 run cannot find your executable:

Verify the entry_points configuration.
Rebuild the workspace using colcon build.
Source the workspace again.

source install/setup.bash

Changes Don't Take Effect

Whenever you:

Add new Python files
Register a new executable
Modify setup.py

remember to rebuild your workspace and source it again.

colcon build
 
source install/setup.bash

Key Takeaways

Install ROS 2 using the official Ubuntu packages.
Always source the ROS environment before using ROS commands.
Use rclpy.spin(node) to keep your node alive and process incoming ROS events.
Register Python nodes inside setup.py using console_scripts.
Rebuild the workspace after making package changes.
Run your node using ros2 run <package> <executable> instead of executing Python files directly.

References

ROS 2 Documentation — https://docs.ros.org/en/jazzy/
ROS 2 Python Tutorials
ROS 2 Client Library (rclpy) Documentation

Getting Started with ROS 2 Python: Installation, First Node, and Executables