MuJoCo Cannot Find OpenGL on macOS

[cverrier]

System Info:

• lerobot version: 0.1.0 (commit c940676)
• Platform: macOS-15.5-arm64-arm-64bit
• Python version: 3.10.18 (virtual environment created with uv, following the contributing guide: uv venv --python 3.10 && source .venv/bin/activate && uv sync --all-extras)
• Huggingface_hub version: 0.30.0
• Dataset version: 3.6.0
• Numpy version: 2.2.6
• PyTorch version (GPU?): 2.7.1 (False)
• Cuda version: N/A
• Using GPU in script?:

I just set up a SO-101 robotic arm, and I am trying to record a dataset following the official tutorial. I ran the following command:

uv run -m lerobot.record \
    --robot.type=so101_follower \
    --robot.port=/dev/tty.usbmodem5A680097201 \
    --robot.id=follower \
    --robot.cameras="{ front: {type: opencv, index_or_path: 0, width: 1920, height: 1080, fps: 5}}" \
    --teleop.type=so101_leader \
    --teleop.port=/dev/tty.usbmodem5A680102791 \
    --teleop.id=leader \
    --display_data=true \
    --dataset.repo_id=${HF_USER}/record-test-grab-bag \
    --dataset.num_episodes=2 \
    --dataset.push_to_hub=False \
    --dataset.single_task="Grab the bag"

I got the following error:

Traceback (most recent call last):
  File "/Users/clementverrier/.local/share/uv/python/cpython-3.10.18-macos-aarch64-none/lib/python3.10/runpy.py", line 196, in _run_module_as_main
    return _run_code(code, main_globals, None,
  File "/Users/clementverrier/.local/share/uv/python/cpython-3.10.18-macos-aarch64-none/lib/python3.10/runpy.py", line 86, in _run_code
    exec(code, run_globals)
  File "/Users/clementverrier/repos/lerobot/lerobot/record.py", line 55, in <module>
    from lerobot.common.policies.factory import make_policy
  File "/Users/clementverrier/repos/lerobot/lerobot/common/policies/factory.py", line 24, in <module>
    from lerobot.common.envs.utils import env_to_policy_features
  File "/Users/clementverrier/repos/lerobot/lerobot/common/envs/utils.py", line 20, in <module>
    import gymnasium as gym
  File "/Users/clementverrier/repos/lerobot/.venv/lib/python3.10/site-packages/gymnasium/__init__.py", line 12, in <module>
    from gymnasium.envs.registration import (
  File "/Users/clementverrier/repos/lerobot/.venv/lib/python3.10/site-packages/gymnasium/envs/__init__.py", line 387, in <module>
    load_plugin_envs()
  File "/Users/clementverrier/repos/lerobot/.venv/lib/python3.10/site-packages/gymnasium/envs/registration.py", line 592, in load_plugin_envs
    fn = plugin.load()
  File "/Users/clementverrier/.local/share/uv/python/cpython-3.10.18-macos-aarch64-none/lib/python3.10/importlib/metadata/__init__.py", line 171, in load
    module = import_module(match.group('module'))
  File "/Users/clementverrier/.local/share/uv/python/cpython-3.10.18-macos-aarch64-none/lib/python3.10/importlib/__init__.py", line 126, in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
  File "/Users/clementverrier/repos/lerobot/.venv/lib/python3.10/site-packages/gymnasium_robotics/__init__.py", line 5, in <module>
    from gymnasium_robotics.envs.maze import maps
  File "/Users/clementverrier/repos/lerobot/.venv/lib/python3.10/site-packages/gymnasium_robotics/envs/maze/__init__.py", line 1, in <module>
    from gymnasium_robotics.envs.maze.ant_maze import AntMazeEnv
  File "/Users/clementverrier/repos/lerobot/.venv/lib/python3.10/site-packages/gymnasium_robotics/envs/maze/ant_maze.py", line 7, in <module>
    from gymnasium.envs.mujoco.ant_v4 import AntEnv
  File "/Users/clementverrier/repos/lerobot/.venv/lib/python3.10/site-packages/gymnasium/envs/mujoco/__init__.py", line 1, in <module>
    from gymnasium.envs.mujoco.mujoco_env import MujocoEnv, MuJocoPyEnv  # isort:skip
  File "/Users/clementverrier/repos/lerobot/.venv/lib/python3.10/site-packages/gymnasium/envs/mujoco/mujoco_env.py", line 20, in <module>
    import mujoco
  File "/Users/clementverrier/repos/lerobot/.venv/lib/python3.10/site-packages/mujoco/__init__.py", line 47, in <module>
    from mujoco.gl_context import *
  File "/Users/clementverrier/repos/lerobot/.venv/lib/python3.10/site-packages/mujoco/gl_context.py", line 44, in <module>
    from mujoco.cgl import GLContext as _GLContext
  File "/Users/clementverrier/repos/lerobot/.venv/lib/python3.10/site-packages/mujoco/cgl/__init__.py", line 21, in <module>
    from mujoco.cgl import cgl
  File "/Users/clementverrier/repos/lerobot/.venv/lib/python3.10/site-packages/mujoco/cgl/cgl.py", line 20, in <module>
    _CGL = ctypes.CDLL('/System/Library/OpenGL.framework/OpenGL')
  File "/Users/clementverrier/.local/share/uv/python/cpython-3.10.18-macos-aarch64-none/lib/python3.10/ctypes/__init__.py", line 374, in __init__
    self._handle = _dlopen(self._name, mode)
OSError: dlopen(/System/Library/OpenGL.framework/OpenGL, 0x0006): tried: '/System/Library/OpenGL.framework/OpenGL' (no such file), '/System/Volumes/Preboot/Cryptexes/OS/System/Library/OpenGL.framework/OpenGL' (no such file), '/System/Library/OpenGL.framework/OpenGL' (no such file, not in dyld cache)

The error indicates that the OpenGL framework library cannot be found at /System/Library/OpenGL.framework/OpenGL, preventing the script from executing.

In my Python virtual environment, I have the following dependencies:

gymnasium==0.29.1
gymnasium-robotics==1.2.4
mujoco==2.3.7

The error is triggered by the following steps:

1. The user runs lerobot/record.py,
2. This imports make_policy(),
3. Which calls env_to_policy_features from lerobot/common/envs/utils.py,
4. Which imports gymnasium,
5. Which loads plugin environments including gymnasium_robotics,
6. Which depends on MuJoCo,
7. Which tries to load the OpenGL framework.

More precisely, MuJoCo tries to load the OpenGL framework from /System/Library/OpenGL.framework/OpenGL, but this location does not exist. This has been fixed in the next MuJoCo release, mujoco==3.0.0, where OpenGL’s location is now correct (at least on my machine).
However, gymnasium_robotics==1.2.4 imposes a constraint that prevents installing mujoco>=3.0.0, hence the error I got before.

Though this constraint has been alleviated in the next release (gymnasium_robotics==1.3.0), which allows having mujoco==3.0.0, we also need to upgrade Gymnasium to gymnasium>=1.0.0…

In LeRobot’s pyproject.toml, I’ve seen that it is already planned to upgrade Gymnasium. However, I haven’t found any related issue in the repository, nor in the TODO’s project page. @Cadene , @aliberts : do you have any update about this? I’ve directly tried upgrading to gymnasium>=1.0.0, but (as expected 😅 ), other version conflicts appeared (e.g., with gym-hil).

I also want to mention that this issue also appears in other places, e.g. in testing: running uv run pytest -sv ./tests leads to

============================================================== short test summary info ===============================================================
ERROR tests/datasets/test_datasets.py - OSError: dlopen(/System/Library/OpenGL.framework/OpenGL, 0x0006): tried: '/System/Library/OpenGL.framework/OpenGL' (no such file), '/System/Volum...
ERROR tests/envs/test_envs.py - OSError: dlopen(/System/Library/OpenGL.framework/OpenGL, 0x0006): tried: '/System/Library/OpenGL.framework/OpenGL' (no such file), '/System/Volum...
ERROR tests/policies/test_policies.py - OSError: dlopen(/System/Library/OpenGL.framework/OpenGL, 0x0006): tried: '/System/Library/OpenGL.framework/OpenGL' (no such file), '/System/Volum...
ERROR tests/test_available.py - OSError: dlopen(/System/Library/OpenGL.framework/OpenGL, 0x0006): tried: '/System/Library/OpenGL.framework/OpenGL' (no such file), '/System/Volum...
ERROR tests/test_control_robot.py - OSError: dlopen(/System/Library/OpenGL.framework/OpenGL, 0x0006): tried: '/System/Library/OpenGL.framework/OpenGL' (no such file), '/System/Volum...
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! Interrupted: 5 errors during collection !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
========================================================== 204 warnings, 5 errors in 2.37s ===========================================================

[CarolinePascal]

Hi @cverrier !

I've been curious about this issue you mentioned on our Discord, and I fear this has to do with our contributing guide which is not up to date (should be resolved soon !).

Could you try again from scratch with the install commands from the up to date documentation ?

Best,

Caroline.

[cverrier]

I installed Miniforge and ran the following commands:

conda create -y -n lerobot python=3.10
conda activate lerobot
conda install ffmpeg -c conda-forge
pip install -e ".[feetech]"

The recording script seems to work correctly now.

If I only do pip install -e ".[feetech]", then I only get gymnasium==0.29.1 installed in the environment (and I don't have mujoco nor gymnasium-robotics anymore). I don't know why it is working though, because it shouldn't (see the discussion regarding dependencies that I wrote in the issue)... Anyway, I've been dealing with conflicts with Python dependencies for a while now, so I am not that surprised 😅

@CarolinePascal thanks for your reply, feel free to close this issue 👍

[CarolinePascal]

Happy that it worked this time ! Though I agree the dependecies issue you had is strange, and even stranger as it seems only two happen with uv and all-extras...

Thank you for the in depth investigation of the dependecies chain, this will definitively help us avoid similar problems in the future !

Best,

Caroline.

[bsprenger]

Hey @CarolinePascal, this issue still occurs with uv on MacOS, which prevents running tests locally. Thank you @cverrier for the very thorough analysis, you saved me a lot of time! I assume that conda bundles OpenGL with it somewhere, which is why the error doesn't occur.

I think it might be worth either:

• Noting this issue in the CONTRIBUTING.md, specifically for MacOS/uv combination. Since uv sync --all-extras prevents running the test suite locally, it's quite hard to contribute using this combo!
• Upgrading to gymnasium 1.0.0, which allows for mujoco 3.0 (aside: is there a reason why lerobot is pinned to gym 0.29?)

[CarolinePascal]

Hi @bsprenger,

Thanks for the update on this issue ! I think CONTRIBUTING.md is being completely reworked without any mention to uv as I'm writing this message.

OpenGL is actually not the only dependency causing problems with uv (see ffmpeg installation issues with torchcodec when using brew), and for the sake of simplicity across OS, we decided to stick with conda.

Regarding gymnasium version, we didn't get the time to properly bump to version 1.0.0 yet :/ It is included in our roadmap, and will be tackled at some point, but feel free to open a PR if you want to speed up the process ;)

Best,

Caroline.