ROS 2のコマンドライン早見表

この早見表は、稼働中のROS 2システムをターミナルからデバッグする人のためのものです。以下のコマンドとフラグはすべて、2026年11月14日にros:jazzy-ros-baseコンテナでros2 <command> -hを実行して確認しました。Jazzyのドキュメントとも照合しています。対象はROS 2 Jazzy Jalisco（LTS、2024年5月リリース）です。Lyrical Luth（LTS、2026年5月リリース）では、たとえばros2 param getなどにオプションが追加されています。新しいディストリビューションでは-hで確認してください。ROS 2が初めての場合は、Hello ROS 2と、用語集のノード、トピック、サービス、アクション、QoSの項目から始めてください。

まず最初に

source /opt/ros/jazzy/setup.bash          # every new shell, or add it to ~/.bashrc
source install/setup.bash                 # your workspace, after colcon build
printenv | grep -E 'ROS_(DISTRO|DOMAIN_ID|AUTOMATIC_DISCOVERY_RANGE)|RMW_IMPLEMENTATION'
ros2 doctor --report | less               # platform, network, middleware and package checks

トピック

ros2 topic list -t                         # names with types
ros2 topic info /scan -v                   # publishers, subscribers and the QoS of each
ros2 topic echo /odom --once               # one message, then exit
ros2 topic echo /odom --field pose.pose.position
ros2 topic echo /scan --no-arr             # hide long arrays
ros2 topic echo /joint_states --csv > joints.csv
ros2 topic hz /camera/image_raw            # rate, averaged over a window
ros2 topic bw /camera/image_raw            # bandwidth
ros2 topic delay /scan                     # age of messages, from header.stamp
ros2 topic find sensor_msgs/msg/Imu
ros2 topic pub --once /cmd_vel geometry_msgs/msg/Twist "{linear: {x: 0.1}, angular: {z: 0.0}}"
ros2 topic pub -r 10 /cmd_vel geometry_msgs/msg/Twist "{linear: {x: 0.1}}"   # 10 Hz until Ctrl-C
ros2 topic pub -t 5 -w 1 /chatter std_msgs/msg/String "{data: hello}"       # 5 messages, after 1 subscriber matches

ノード

ros2 node list
ros2 node list -a                          # include hidden nodes
ros2 node info /controller_manager         # its topics, services and actions

サービス

ros2 service list -t
ros2 service type /add_two_ints
ros2 service find std_srvs/srv/Trigger
ros2 service call /reset std_srvs/srv/Empty
ros2 service call /add_two_ints example_interfaces/srv/AddTwoInts "{a: 2, b: 3}"
ros2 service echo /add_two_ints            # needs service introspection enabled on the client or server

パラメータ

ros2 param list /camera_driver
ros2 param get /camera_driver exposure
ros2 param set /camera_driver exposure 20
ros2 param describe /camera_driver exposure
ros2 param dump /camera_driver > camera.yaml
ros2 param load /camera_driver camera.yaml
ros2 param delete /camera_driver debug_mode

バッグ

Jazzyのデフォルトのストレージ形式はMCAPです。Jazzyではトピックを--topicsで渡します。トピックを位置引数としてそのまま並べる書き方は非推奨です。

ros2 bag record -a -o run_01                         # all topics and services
ros2 bag record --topics /tf /tf_static /odom /scan -o nav_test
ros2 bag record -e '/camera/.*' -o cams              # regex
ros2 bag record --topics /scan -d 60 -o split_bag    # new file every 60 s
ros2 bag info nav_test
ros2 bag play nav_test -r 0.5                        # half speed
ros2 bag play nav_test --clock -l                    # publish /clock and loop
ros2 bag play nav_test --topics /scan --start-offset 10

--clockを付けてバッグを再生するときは、テスト対象のノードをuse_sim_timeをtrueにして実行してください。そうしないと、ノードのタイムスタンプがデータと一致しません。

アクション

ros2 action list -t
ros2 action info /navigate_to_pose
ros2 action type /navigate_to_pose
ros2 action send_goal -f /fibonacci example_interfaces/action/Fibonacci "{order: 5}"   # -f prints feedback

インターフェース

ros2 interface list
ros2 interface packages
ros2 interface package sensor_msgs
ros2 interface show geometry_msgs/msg/Quaternion   # fields x, y, z, w
ros2 interface proto geometry_msgs/msg/Twist       # a YAML template to paste into pub or call

実行と起動

ros2 run demo_nodes_cpp talker
ros2 run demo_nodes_cpp talker --ros-args -r __node:=talker_2 -r chatter:=chatter_2
ros2 run demo_nodes_cpp parameter_blackboard --ros-args -p a_string:=hello --params-file demo_params.yaml
ros2 run demo_nodes_cpp talker --ros-args --log-level debug
ros2 run --prefix 'gdb -ex run --args' demo_nodes_cpp talker
ros2 launch nav2_bringup tb3_simulation_launch.py --show-args
ros2 launch my_robot bringup.launch.py use_sim_time:=true
ros2 launch my_robot bringup.launch.py --print       # show the launch description without running it

パッケージとデーモン

ros2 pkg list
ros2 pkg executables demo_nodes_cpp
ros2 pkg prefix rclpy
ros2 pkg create my_pkg --build-type ament_python --dependencies rclpy std_msgs --node-name my_node
ros2 pkg xml my_pkg
ros2 daemon stop && ros2 daemon start                 # clears a stale discovery cache
ros2 doctor hello                                     # check that hosts see each other

QoSフラグ

ros2 topic echoとros2 topic pubは同じQoSオプションを受け付けます。

フラグ	値
`--qos-profile`	`default`, `system_default`, `sensor_data`, `services_default`, `parameters`, `parameter_events`, `action_status_default`, `best_available`
`--qos-reliability`	`reliable`, `best_effort`, `system_default`, `best_available`
`--qos-durability`	`volatile`, `transient_local`, `system_default`, `best_available`
`--qos-history`, `--qos-depth`	深さを指定した`keep_last`、または`keep_all`

Jazzyのヘルプによれば、echoとpubはデフォルトで、すでに動いているエンドポイントと互換性のある信頼性（reliability）と永続性（durability）を選びます。相手側が後から起動する場合や、特定のプロファイルを試したい場合にはフラグが必要です。

ros2 topic echo /map --qos-durability transient_local --qos-reliability reliable
ros2 topic pub /scan_status std_msgs/msg/String "{data: ok}" --qos-reliability best_effort

JazzyのQoSのページにある互換性のルールは次のとおりです。

パブリッシャ	サブスクライバ	接続
Best effort	Best effort	する
Best effort	Reliable	しない
Reliable	Best effort	する
Reliable	Reliable	する
Volatile	Transient local	しない
Transient local	Volatile	する（新しいメッセージのみ）
Transient local	Transient local	する（保存済みの履歴も含む）

次のコードは、表の2行目を実際に確かめるものです。Jazzyのコンテナで動作し、best effortのパブリッシャを1つと、reliableとbest effortのサブスクライバを1つずつ作ります。

# ros2
import rclpy
from rclpy.qos import QoSProfile, ReliabilityPolicy
from std_msgs.msg import String

rclpy.init()
node = rclpy.create_node("qos_check")
best_effort = QoSProfile(depth=10, reliability=ReliabilityPolicy.BEST_EFFORT)
reliable = QoSProfile(depth=10, reliability=ReliabilityPolicy.RELIABLE)
received = {"reliable_sub": 0, "best_effort_sub": 0}

pub = node.create_publisher(String, "scan_status", best_effort)
node.create_subscription(String, "scan_status", lambda m: received.__setitem__("reliable_sub", received["reliable_sub"] + 1), reliable)
node.create_subscription(String, "scan_status", lambda m: received.__setitem__("best_effort_sub", received["best_effort_sub"] + 1), best_effort)

for i in range(40):
    pub.publish(String(data=f"msg {i}"))
    rclpy.spin_once(node, timeout_sec=0.05)
print("best-effort publisher ->", received)   # the reliable subscription stays at 0
node.destroy_node()
rclpy.shutdown()

ROS 2 Jazzyでの出力です。タイムスタンプと、対応するパブリッシャ側の警告は削除しています。

[WARN] [qos_check]: New subscription discovered on topic 'scan_status', requesting incompatible QoS. No messages will be sent to it. Last incompatible policy: RELIABILITY
best-effort publisher -> {'reliable_sub': 0, 'best_effort_sub': 38}

/mapや/robot_descriptionのようなラッチ型のトピックに後から参加したサブスクライバは、両側がtransient localのdurabilityを使っていない限り、何も受信しません。

よくある落とし穴

症状	原因	対処
`ros2 topic list`に別のマシンのトピックが何も表示されない	`ROS_DOMAIN_ID`が異なる、`ROS_AUTOMATIC_DISCOVERY_RANGE`でディスカバリが制限されている、またはファイアウォールがマルチキャストをブロックしている	両方のマシンでドメインIDを揃え、ディスカバリ範囲を確認し、両方で`ros2 doctor hello`を実行する
終了させたノードがまだ一覧に表示される	CLIデーモンがディスカバリ情報をキャッシュしている	`ros2 daemon stop`の後で再試行する
`echo`に何も表示されないが、`info -v`には両端が表示される	QoSの不一致	`ros2 topic info -v`でQoSを比較し、上記のフラグを使う
ビルド直後に`Package 'x' not found`が出る	このシェルでワークスペースをsourceしていない	`source install/setup.bash`
バッグ再生中にTFのルックアップが失敗する	ノードは実時間（wall time）を使い、バッグには古いタイムスタンプが入っている	`ros2 bag play --clock`と`use_sim_time:=true`
`ros2 param set`は応答するが何も変わらない	ノードが起動時にしかパラメータを読まない	ノードを再起動するか、コードにパラメータコールバックを追加する
`pub`のメッセージが消える	ディスカバリが完了する前にパブリッシャが終了する	`-w 1`を使うか、レートを指定して`-t N`を使う
同じネットワーク上の2つのシミュレータがトピックを奪い合う	共有ネットワーク上で同じドメインを使っている	ロボットや開発者ごとに別の`ROS_DOMAIN_ID`を割り当てる