macOS环境安装CVAT开发版 pip安装av依赖包报错如何修复

核心原因 #

安装过程跳过了预编译二进制包，强制走源码编译流程，但本地环境没有安装FFmpeg开发库，或是pyenv管理的Python没有正确识别Homebrew安装的依赖路径，导致pkg-config无法检索到所需的FFmpeg组件。

分步修复操作 #

• 1. 安装系统层依赖
     Intel架构Mac下执行Homebrew命令安装全量FFmpeg和pkg-config工具：

  brew install ffmpeg pkg-config
  

  安装完成后执行验证命令，确认依赖可被正常检索：

  pkg-config --libs libavformat libavcodec libavdevice libavutil libavfilter libswscale libswresample
  

  命令无报错、输出链接参数即为正常。

• 2. 配置pyenv环境的依赖搜索路径
     Intel Mac的Homebrew安装前缀为/usr/local，pyenv默认不会主动加载该路径下的库文件，执行pip安装前先临时导出环境变量：

  export LDFLAGS="-L/usr/local/lib"
  export CPPFLAGS="-I/usr/local/include"
  export PKG_CONFIG_PATH="/usr/local/lib/pkgconfig"
  

• 3. 优先使用预编译包安装（最快解决方式）
     日志中明确提示Skipping wheel build for av, due to binaries being disabled for it，说明当前pip配置禁用了预编译二进制包，强制走源码编译才触发依赖错误。直接执行命令强制使用预编译wheel安装对应版本的PyAV，不需要本地编译：

  pip install av==8.0.2 --prefer-binary
  

  安装成功后再执行原依赖安装命令即可：

  pip install -r cvat/requirements/development.txt
  

异常排查 #

如果上述操作仍失败，按以下点逐一排查：

• 先执行pip cache purge清除旧的编译缓存，避免残留的失败安装包影响结果
• 执行brew --prefix ffmpeg确认FFmpeg安装路径，如果自定义过Homebrew安装位置，将实际的lib/pkgconfig路径替换到PKG_CONFIG_PATH环境变量中
• 安装时暂时移除conda、miniforge等环境的PATH配置，避免不同来源的FFmpeg版本冲突
• 检查pip配置文件是否存在no-binary = :all:这类全局配置，临时注释该配置后再执行安装

内容的提问来源于stack exchange，提问作者Raman