踩坑/unitree_sdk2_python·18 天前

macOS 安装 Unitree SDK2 Python 卡在 cyclonedds

解释 macOS 安装失败的原因，以及开发机和机器人局域网 Ubuntu 机器之间的正确分工。

• 本体 SDK 与控制

宇树 G1

问题现象与根因

macOS 安装失败不是待修复的项目缺陷

在 macOS 上直接执行 pip install unitree_sdk2py，安装过程会停在 cyclonedds 依赖：当前依赖链没有可用的 macOS wheel，因此本地环境无法按这条路径完成安装。反复切换 Python 小版本、修改业务代码或强行拼装依赖，不能改变运行平台不受支持这一事实，反而容易制造一套无法复现的个人环境。

正确做法是按机器职责拆分。macOS 开发机只承担内容、云端逻辑、接口开发和模拟运行，不发起面向真实机器人的 SDK 通信。需要执行真机脚本时，改用已经接入机器人局域网的 Ubuntu 机器，在该机器上建立独立 Python 环境并安装、验证 SDK。这样既符合网络接入条件，也避免把真机依赖扩散到日常开发环境。

排查时先确认失败包确实是 cyclonedds，再检查当前系统是不是 macOS。若两项同时成立，应把结果记录为预期的不兼容环境，并转到 Ubuntu 真机工作站继续，而不是把“在 macOS 上装成功”当作交付目标。SDK 版本、机器人型号和网络条件仍需在实际运行记录中单独注明。

排查与解决步骤

1. 核对架构与依赖版本：确认 macOS (arm64 / Apple Silicon) 下 Python 虚拟环境与 cyclonedds C 动态库架构一致，设置 CYCLONEDDS_HOME 指向编译安装目录。
2. 绑定物理网卡接口：在 CycloneDDS XML 配置中将 <NetworkInterfaceAddress> 显式指定为连接到机器人的有线以太网接口（如 en0 或 en5），避免默认绑定到回环或 Wi-Fi 接口导致组播丢包。
3. 验证 DDS 话题连通性：运行示例前先通过高层状态订阅脚本验证 rt/sportmodestate 话题周期是否稳定在 50Hz~500Hz。

来源

本页事实对应的公开页面，以原文为准。

1. unitree_sdk2_python访问 2026-10-10