# MuJoCo Studio Windows版缺失headless_ui致Web Viewer启动失败

> 原文链接：https://robotics.hellobike.com/pitfalls/2026-11-07-mujoco-3580
> 频道：pitfalls | 更新日期：2026-11-07 | 标签：auto, github-issue, mujoco
> 核心摘要：MuJoCo 4.0.0 Windows wheel未编译Web模块导致ImportError，Linux/macOS已修复，Windows需切换平台或等待官方重发wheel。

# MuJoCo Studio Windows版缺失headless_ui致Web Viewer启动失败

::: v-pre
> 本文由 AI 根据公开内容整理，可能有误，请以原文为准：[Studio web viewer is unusable: studio.web.headless_ui is missing from the wheel](https://github.com/google-deepmind/mujoco/issues/3580)（GitHub google-deepmind/mujoco #3580）

**状态**：有绕过办法

## 问题

在Windows 11运行`python -m mujoco.studio.viewer --gfx=web`时报错`ImportError: cannot import name 'headless_ui' from 'mujoco.studio.web'`。

## 环境

MuJoCo 4.0.0 (cp313-cp313-win_amd64), Python 3.13, Windows 11; 对比环境: MuJoCo 3.13.0/4.0.0 Linux/macOS wheel正常

## 解决办法

1. 确认当前Windows wheel缺陷：对比PyPI上`win_amd64`与`manylinux`/`macosx` wheel，验证是否缺失`mujoco/studio/web/dist/`目录及`_studio`中的`headless_ui`模块。
2. 临时绕过方案：将开发或仿真任务迁移至Linux或macOS环境，使用已包含完整Web组件的对应wheel。
3. 避免无效调试：不要尝试手动补全文件或修改代码，因核心C++扩展`headless_ui`未在Windows编译，无法通过纯Python补丁修复。
4. 关注上游修复：等待维护者重新发布启用`MUJOCO_STUDIO_WITH_WEB`编译选项的Windows wheel。
5. Native模式替代测试：若仅需可视化且不依赖Web后端，可尝试其他GFX模式，但需注意Windows下Native Viewer目前也存在`ValueError: Target not found`渲染异常，建议优先使用Linux环境…

讨论原作者：@larrygao001 等，版权归原作者所有。
:::

## 原始参考来源 (Sources)

- [GitHub google-deepmind/mujoco #3580：Studio web viewer is unusable: studio.web.headless_ui is missing from the wheel](https://github.com/google-deepmind/mujoco/issues/3580)