はじめに

ROS（Robot Operating System）でアームロボットを動かそうとした際に、突然moveit_commander.MoveGroupCommanderが見当たらないと怒られた経験はありませんか？
本記事は、そんなAttributeErrorに遭遇したROS初学者〜中級者を対象に、エラーの根本的な原因と「なぜそうなるのか」を図解付きで解説します。
記事を読み終える頃には、MoveIt!のPythonインターフェースが正しく使えるようになるだけでなく、「ROSでモジュールが見つからない」という同種のエラーにも自力で対処できるようになります。

前提知識

  • Ubuntu 20.04 または 22.04 でROS Noetic／ROS 2 Foxy 以降の環境を利用している
  • catkin/catkin_toolsまたはcolconによるワークスペース構築に慣れている
  • Python 3 でのモジュールインポートの基礎知識（import文の意味）
  • MoveIt!がロボットの運動計画ライブラリであることは知っているが、まだ動かしたことがない

エラーの概要と背景

よくあるエラーメッセージ

Python

import moveit_commander
group = moveit_commander.MoveGroupCommander("arm")
# AttributeError: module 'moveit_commander' has no attribute 'MoveGroupCommander'

この一文は「MoveIt!のチュートリアルどおりに書いたはずなのに動かない！」という問いをROS AnswersやGitHub Discussionsに大量生産してきました。
端的に言うと、「Pythonが参照しているmoveit_commanderが、あなたが期待しているパッケージではない」か「正しいパッケージがインストールされていない」かのどちらかです。

なぜ「見つからない」のか

  1. 同名ディレクトリの存在
    ワークスペース内にmoveit_commander/という名前のディレクトリ（自作ノードや空ディレクトリ）を作ってしまうと、Pythonがそちらを優先的に参照します。
  2. apt と ソース混在
    sudo apt install ros-noetic-moveitでバイナリを入れつつ、同時にソースからmoveitをビルドしていると、Pythonのパスが二転三転します。
  3. ROS 2 との混同
    ROS 2のmoveit2ではMoveGroupCommanderの代わりにMoveGroupInterfaceが使われるため、チュートリアルを間違えて参照しているケースもあります。

原因を特定し、確実に動かすまでの手順

ステップ1：Pythonが参照しているモジュールを確認する

ターミナルで以下を実行し、実際にどこからmoveit_commanderがロードされているかを特定します。

Bash

# システムPythonの場合
python3 -c "import moveit_commander, inspect, os; print(os.path.dirname(inspect.getfile(moveit_commander)))"

# ROS環境を読み込んでいる場合
source /opt/ros/noetic/setup.bash
python3 -c "import moveit_commander, inspect, os; print(os.path.dirname(inspect.getfile(moveit_commander)))"

正しくインストールされていれば、以下のようなパスが表示されます。

  • /opt/ros/noetic/lib/python3/dist-packages/moveit_commander（aptでインストール）
  • ~/catkin_ws/devel/lib/python3/dist-packages/moveit_commander（ソースビルド）

もし現在のディレクトリやワークスペースのsrc以下が表示されたら「同名ディレクトリが存在する」と言うことです。

ステップ2：同名ディレクトリ／空フォルダを削除する

ワークスペース内を検索し、不用意に作ってしまったmoveit_commanderフォルダを消去します。

Bash

# ワークスペースのトップで実行
find . -type d -name "moveit_commander"
# 該当ディレクトリがなければOK。あれば削除 or リネーム

ステップ3：正しいパッケージをインストールする

aptで一発で入れたい場合：

Bash

sudo apt update
sudo apt install ros-noetic-moveit ros-noetic-moveit-commander
# ROS 2の場合
sudo apt install ros-foxy-moveit-msgs ros-foxy-moveit

ソースから最新版を使いたい場合：

Bash

cd ~/catkin_ws/src
git clone https://github.com/ros-planning/moveit.git -b noetic-devel
rosdep install -y --from-paths . --ignore-src
catkin build  # or catkin_make

ステップ4：ワークスペースをクリーンにして再ビルド

依存関係のキャッシュが腐っていることもあるため、一度クリーンからやり直しましょう。

Bash

catkin clean -y
catkin build
# そして環境再読込
source devel/setup.bash

ステップ5：動作確認スクリプトで実行

以下の最小スクリプトをtest_moveit.pyとして作成し実行。

Python

#!/usr/bin/env python3
import sys
import rospy
import moveit_commander

def main():
    moveit_commander.roscpp_initialize(sys.argv)
    rospy.init_node("test_node", anonymous=True)
    robot = moveit_commander.RobotCommander()
    print("Robot frame:", robot.get_planning_frame())
    group = moveit_commander.MoveGroupCommander("arm")
    print("End effector link:", group.get_end_effector_link())
    moveit_commander.roscpp_shutdown()

if __name__ == "__main__":
    main()

Bash

chmod +x test_moveit.py
rosrun <your_package> test_moveit.py
# エラーが出なければOK

ハマりどころとトラブルシューティング

症状 原因 解決策
ImportError: No module named 'moveit_commander' パッケージ未インストール／環境未読み込み aptでインストール or ワークスペースをsource
RLException: Unable to contact ROS master roscoreが上がっていない 別ターミナルでroscore実行
MoveGroupCommanderはインポートできるが計画が通ら ロボットモデル／SRDFが読み込まれていない roslaunch <robot>_moveit_config demo.launch で動作確認
同名のmoveit_commander.pyファイルがある 自作ファイルが優先される ファイル名を変えるか移動

まとめ

本記事では、ROSでMoveIt!を使う際の代表格エラー「moveit_commanderにMoveGroupCommanderがない」の原因を整理し、 - Pythonパスの優先順位 - aptとソース混在の落とし穴 - 同名ディレクトリ・ファイルの衝突 を踏まえた上で、正しい環境構築手順を紹介しました。

  • エラーログを見て「見つからない」とだけ怒られたとしても、実際の参照先を特定することが第一
  • ワークスペース内に不用意に作った同名フォルダが犯人になることが多い
  • 環境を一掃してapt or ソースのどちらかに統一することがトラブルを減らす近道

これでMoveIt!のPython APIを使った運動計画サンプルがスムーズに動くはずです。
次回は、実際にMoveGroupCommanderで複数の制約（Constraints）を与えて複雑な動作を生成するチュートリアルを予定しています。

参考資料