系统依赖安装
概述
本文档提供 py-xiaozhi 项目的完整依赖安装指南，包括系统级依赖和 Python 环境配置。请按照文档顺序进行安装。
兼容范围：Ubuntu 20.04 / 22.04 / 23.10 / 24.04 / 25.xx。 Qt 安装来源统一：仅使用 pip 或 conda 安装 PyQt5（不要使用 apt 的 python3-pyqt5）。ARM Ubuntu（aarch64）强烈推荐 conda 安装 PyQt。
系统依赖安装
Windows
多媒体组件
bash
# 使用 Scoop 安装（推荐）
scoop install ffmpeg
# 或使用 Conda
conda install -c conda-forge ffmpeg opus手动安装FFmpeg
- 下载：BtbN/FFmpeg-Builds
- 解压后将
bin目录添加至系统环境变量PATH
Opus音频编解码器
项目已包含
opus.dll，通常无需额外安装如遇问题，可将
/libs/windows/opus.dll复制到：- 应用程序运行目录
C:\Windows\System32
Linux (Debian/Ubuntu)
兼容 Ubuntu 20/22/23/24/25。以下命令对上述版本均适用；个别极简镜像如缺包按提示补装即可。 请不要安装 apt 的
python3-pyqt5*，Qt 仅走 pip/conda。
核心依赖
bash
# 更新包管理器
sudo apt-get update
# 安装核心依赖（不含 Qt）
sudo apt-get install -y portaudio19-dev libportaudio2 ffmpeg libopus0 libopus-dev \
build-essential python3-venv python3-pip libasound2-dev \
libxcb-xinerama0 libxkbcommon-x11-0libxcb-xinerama0、libxkbcommon-x11-0：Qt GUI 在部分桌面环境可能缺失的运行库；装上更稳。音频系统（三选一即可）：
PulseAudio 工具（推荐）：
bashsudo apt-get install -y pulseaudio-utilsALSA：
bashsudo apt-get install -y alsa-utilsALSA + 交互工具：
bashsudo apt-get install -y alsa-utils expect
提示：Ubuntu 24+ 默认 PipeWire，但
pulseaudio-utils通过pipewire-pulse兼容层仍可用，不影响本项目。
开发工具（可选）
bash
sudo apt-get install -y gcc g++ make cmake pkg-configmacOS
bash
# 使用 Homebrew 安装
brew install portaudio opus ffmpeg gfortran
brew upgrade tcl-tk
# 安装 Xcode 命令行工具（如未安装）
xcode-select --installPython环境配置
方式一：使用Miniconda（推荐）
1. 下载Miniconda
| 操作系统 | 架构 | 下载命令 |
|---|---|---|
| Linux | x86_64 | wget -O Miniconda3-latest-Linux-x86_64.sh https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh |
| Linux | ARM64 | wget -O Miniconda3-latest-Linux-aarch64.sh https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-aarch64.sh |
| macOS | Intel | wget -O Miniconda3-latest-MacOSX-x86_64.sh https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-x86_64.sh |
| macOS | Apple Silicon | wget -O Miniconda3-latest-MacOSX-arm64.sh https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-arm64.sh |
| Windows | x86_64 | 下载链接 |
2. 安装Miniconda
Linux/macOS
bash
# 添加执行权限
chmod +x Miniconda3-latest-*.sh
# 运行安装程序
./Miniconda3-latest-*.sh安装过程中的选择：
- 许可协议：按
Enter或q跳过，输入yes接受 - 安装路径：使用默认路径（推荐）
- 初始化：输入
yes（推荐）
3. 配置环境（如需要）
bash
# 如环境变量未自动配置
echo 'export PATH="$HOME/miniconda3/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
# 初始化conda
conda init4. 验证安装
bash
conda --version5. 优化配置
bash
# 关闭自动激活base环境
conda config --set auto_activate_base false
# 添加conda-forge频道
conda config --add channels conda-forge方式二：使用系统Python + venv
bash
# 创建虚拟环境
python3 -m venv .venv
# 激活虚拟环境
# Linux/macOS
source .venv/bin/activate
# Windows
.venv\Scripts\activate（统一）Qt 用 pip/conda 安装
仅使用 pip 或 conda 安装 PyQt5，不使用 apt 的 PyQt。 ARM Ubuntu（aarch64）强烈建议：Conda 安装 PyQt；x86_64 可用 pip 或 conda。二者不要混用。
路线 B1：Conda 安装 PyQt（ARM Ubuntu 推荐）
bash
# 建议的最小系统依赖（已在“核心依赖”中安装过可跳过）
sudo apt-get update
sudo apt-get install -y libportaudio2 portaudio19-dev ffmpeg libopus0 \
libasound2-dev libxcb-xinerama0 libxkbcommon-x11-0
# 创建并进入环境
conda create -n py-xiaozhi python=3.10 -y
conda activate py-xiaozhi
# 用 conda 安装 PyQt 与 C++ 运行库（避免 GLIBCXX 问题）
conda install -c conda-forge -y pyqt=5.15 libstdcxx-ng>=13 libgcc-ng>=13
# PortAudio 绑定（2选1）
# A) 用系统 libportaudio（已 apt 安装）
pip install sounddevice
# B) 全交给 conda（不依赖系统）
# conda install -c conda-forge -y portaudio jack python-sounddevice
# 其他依赖
pip install -r requirements.txt # 确保 requirements.txt 里不要包含 PyQt5路线 B2：pip 安装 PyQt（x86_64 较稳；ARM 可能无轮子，不推荐）
bash
# 若 fallback 到源码构建可能需要的 dev 依赖（仅在失败时再装）
sudo apt-get install -y build-essential python3-dev \
qtbase5-dev qtchooser qt5-qmake qtmultimedia5-dev
# venv
python3 -m venv .venv
source .venv/bin/activate
# 安装 PyQt（ARM 若无 manylinux 轮子则会尝试本机构建，失败请改用 conda 方案）
pip install "PyQt5==5.15.*" PyQt5-Qt5 PyQt5-sip
# 其他依赖
pip install -r requirements.txt # 同样不要再装 PyQt5不要混用：
- 选了 pip/conda 的 PyQt，就不要
apt install python3-pyqt5*。- 选了 apt 的 PyQt（本文件已移除该方案），就不要再 pip/conda 安装 PyQt。
包管理器优化
换源工具（推荐）
bash
# Windows（PowerShell管理员权限）
winget install RubyMetric.chsrc --source winget
# Linux/macOS
wget -O- aslant.top/chsrc.sh | sudo bash
# 配置pip源
chsrc set pip手动配置pip源
bash
# 使用阿里云镜像源
pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/
pip config set install.trusted-host mirrors.aliyun.com项目依赖安装
1. 创建项目环境
bash
# 使用Conda（推荐）
conda create -n py-xiaozhi python=3.10 -y
conda activate py-xiaozhi
# 或使用venv
python3 -m vvenv .venv
source .venv/bin/activate # Linux/macOS
# .venv\Scripts\activate # Windows2. 安装Python依赖
bash
# Linux/Windows
pip install -r requirements.txt
# macOS
pip install -r requirements_mac.txt3. 验证安装
bash
# 检查关键依赖（按你选的路线，PyQt 由 conda 或 pip 提供）
python -c "import sounddevice; print('SoundDevice OK')"
python -c "import opuslib; print('Opus OK')"
python -c "import PyQt5.QtCore as q; print('PyQt5 OK, Qt', q.QT_VERSION_STR)"故障排除
常见问题
SoundDevice安装失败
bash
# Ubuntu/Debian
sudo apt-get install -y portaudio19-dev libasound2-dev libportaudio2
# macOS
brew install portaudio
# Windows
pip install sounddevicePyQt5安装失败
- Conda 路线（推荐 ARM）：
bash
conda install -c conda-forge -y pyqt=5.15 libstdcxx-ng>=13 libgcc-ng>=13- pip 路线（x86_64 为主）：确认是否有 manylinux 轮子；ARM 若源码构建失败，请改用 conda。
Opus库缺失
- macOS 用户优先用 conda 安装（否则需自行处理动态库路径）：
bash
conda install -c conda-forge opus
# 如确有需要：
# nano ~/.zshrc
# export DYLD_LIBRARY_PATH=/opt/homebrew/lib:$DYLD_LIBRARY_PATH
# source ~/.zshrc- Linux
bash
sudo apt-get install -y libopus0 libopus-dev- macOS
bash
brew install opus权限问题（Linux）
bash
# 将用户添加到audio组
sudo usermod -a -G audio $USER
# 重新登录后生效版本要求
- Python: 3.9.13+ (推荐3.10，最高3.11)
- PyQt5: 5.15+
- SoundDevice: 0.4.4+
- FFmpeg: 4.0+
- Opus: 1.3+
- PortAudio: 19.0+
注意事项
- 建议使用 Conda 环境管理依赖（ARM Ubuntu 安装 PyQt 强烈推荐 conda）
- 不要与 esp32-server 共用 Conda 环境
- macOS 用户必须使用
requirements_mac.txt - Windows 用户无需手动安装
opus.dll - 项目使用 SoundDevice 替代 PyAudio，使用 PyQt5 作为 GUI 框架
- 确保系统依赖安装完成后再安装 Python 依赖
- 使用国内镜像源可提高下载速度
- 不要混用 PyQt 安装来源：仅使用 pip 或 conda，不要使用 apt 的 python3-pyqt5*