MuJoCoのビューアが開かない・固まるときの原因と直し方

MuJoCoのビューアが開かない・固まるときの原因は、ほぼ次の3つに絞られます。「表示先がない（クラウドやSSH先にDISPLAYがない）」「macOSでlaunch_passiveをpythonから直接呼んでいる」「自分で書いたループでsync()を呼んでいない」。**ビューア（Viewer）**とは、MuJoCoに標準搭載された、物理シミュレーションの様子をリアルタイムで3D表示する可視化ウィンドウのことです。この記事では、症状別の原因と直し方を、公式ドキュメントで確認した内容と筆者が実際に再現した結果で整理します。

まず症状を確認する

次の章から、それぞれの原因と直し方を詳しく見ていきます。

症状1: 「DISPLAY environment variable is missing」で終了する

これは、ビューア用のウィンドウを表示する画面（ディスプレイ）が、今のマシンにないことが原因です。クラウドの仮想マシンやコンテナ、SSH接続先のLinuxサーバーでMuJoCo入門のコードをそのまま動かすと、この状態になります。

筆者も、GUIのないLinuxコンテナで次のコードを実行し、実際にこのエラーを再現しました。

import mujoco
import mujoco.viewer
 
model = mujoco.MjModel.from_xml_string("<mujoco/>")
data = mujoco.MjData(model)
mujoco.viewer.launch_passive(model, data)

GLFWError: (65550) b'X11: The DISPLAY environment variable is missing'
ERROR: could not initialize GLFW

MuJoCoのビューアはGLFWというライブラリでウィンドウを開きますが、GLFWはLinux上ではX11（画面を表示する仕組み）を前提にしているため、DISPLAYがないと初期化自体に失敗します。

xvfb-run -a python your_script.py

症状2: macOSで実行しても何も起きない・すぐ終わる

自分で書いたPythonスクリプトの中でmujoco.viewer.launch_passive()を呼んでいる場合、macOSではpythonコマンドの代わりにmjpythonコマンドで実行する必要があります。これは公式ドキュメントに明記されているmacOS特有の制約で、理由は「ウィンドウの描画はメインスレッドで行う必要があるが、通常のpythonでは別スレッドになってしまう」ためです¹。

# macOSでlaunch_passiveを使うスクリプトを動かすとき
mjpython your_script.py

mjpythonはmujocoパッケージに同梱されていて、公式ドキュメントでは「pythonコマンドの完全な代替として使え、同じコマンドライン引数がそのまま使える」と説明されています¹。ターミナルで直接python -m mujoco.viewerを実行して様子がおかしいときも、mjpython -m mujoco.viewerに置き換えて試してみてください。

症状3: ウィンドウは開くが真っ暗・固まったまま動かない

MuJoCo入門のようにビューアへドラッグ&ドロップするだけなら自動で描画されますが、自分でシミュレーションループを書いてlaunch_passiveに渡している場合、ループの中でviewer.sync()を呼んでいないと画面が更新されません。公式ドキュメントは次のように説明しています。

ユーザースクリプトは、ビューアが物理状態の変化を反映できるようにsync()を呼び出す必要がある²

正しい最小ループは次の形です。

import mujoco
import mujoco.viewer
 
model = mujoco.MjModel.from_xml_string("""
<mujoco>
  <worldbody>
    <light pos="0 0 3"/>
    <geom type="plane" size="2 2 0.1"/>
    <body pos="0 0 1"><freejoint/><geom type="box" size="0.1 0.1 0.1"/></body>
  </worldbody>
</mujoco>
""")
data = mujoco.MjData(model)
 
with mujoco.viewer.launch_passive(model, data) as viewer:
    while viewer.is_running():
        mujoco.mj_step(model, data)
        viewer.sync()  # これを忘れると画面が固まったまま

さらに、カメラの向きや表示オプション（viewer.camやviewer.opt）を自分のスクリプトから直接書き換える場合は、sync()の外側でviewer.lock()を使ってロックを取ってから変更する必要があります。ビューアは専用スレッドで動いているため、ロックなしで触ると競合が起きます³。

python -m mujoco.viewer と launch_passive の違い

どちらも同じビューアですが、使い方の目的が違います。

「とりあえずモデルの見た目を確認したい」なら前者、「自分のコードでステップを進めながら可視化したい」なら後者、というのが基本的な使い分けです。

よくある質問

まとめ

• 「DISPLAY environment variable is missing」は表示先がない環境特有のエラー。Xvfbで仮想ディスプレイを用意すれば起動できる（実際に確認済み）
• macOSで自作スクリプトからlaunch_passiveを使うときはpythonではなくmjpythonで実行する（公式ドキュメント）
• 画面が固まるときは、ループ内のsync()忘れをまず疑う
• 「見た目を素早く確認したい」ならpython -m mujoco.viewerへのドラッグ＆ドロップ、「自分のコードに組み込みたい」ならlaunch_passive

もう少し詳しく（背景）

MuJoCoの標準ビューアはGLFWでウィンドウを作成しますが、GLFWはLinux上ではX11プロトコルに依存するため、X11サーバーに接続できない（＝DISPLAYがない）環境では初期化できません⁴。これはMuJoCo固有の制約ではなく、GLFWを使うアプリ全般に共通する挙動です。macOSのmjpython要件は、Apple製OS特有のGUIイベント処理の都合（描画はメインスレッドでなければならない）に対応するためのものです¹。launch_passiveが別スレッドでビューアを動かす設計になっているのは、ユーザーのPythonコード（強化学習の学習ループなど）をブロックせずに裏側で可視化を続けられるようにするためで、その代わりにsync()とlock()でメインのシミュレーションコードとの整合性を取る仕組みになっています²³。

次の一歩 🌸

ビューアが動くようになったら、MuJoCo入門で振り子のシミュレーションから練習しましょう。Python環境そのものが不安ならPython環境構築の第一歩へ。シミュレーションでの練習を実機につなげる考え方はSim-to-Realの実践、本格的なGPUシミュレータが必要になったらNVIDIA Isaac Sim入門も合わせてどうぞ。