PY-XIAOZHI

English

简体中文

English

简体中文

Appearance

System Dependencies Installation ​

Overview ​

This document provides a complete dependency installation guide for the py-xiaozhi project.

Tech Stack:

  • Python >= 3.10
  • GUI: PySide6
  • Package Management: uv (recommended) / pip

System Dependencies ​

Windows ​

bash
# Install with Scoop (recommended)
scoop install ffmpeg

# Or with winget
winget install FFmpeg

Opus Codec: The project already includes opus.dll, so no additional installation is usually needed. If you encounter issues, copy /libs/windows/opus.dll to the application directory or C:\Windows\System32.

macOS ​

bash
# Homebrew installation
brew install portaudio opus ffmpeg

# Xcode Command Line Tools
xcode-select --install

Linux (Debian/Ubuntu) ​

Compatible with Ubuntu 20.04 / 22.04 / 24.04 / 25.04 and Raspberry Pi OS

Choose the appropriate installation command based on your system version. Different versions have different ALSA package names and default audio servers.

Check system version:

bash
lsb_release -d  # or cat /etc/os-release

Default audio server: PipeWire (compatible with PulseAudio)

bash
sudo apt-get update
sudo apt-get install -y \
    portaudio19-dev libportaudio2 \
    ffmpeg libopus0 libopus-dev \
    libasound2-dev \
    pulseaudio-utils \
    libxcb-xinerama0 libxkbcommon-x11-0 \
    build-essential python3-venv python3-pip

Ubuntu 24.04 / 25.04 ​

Default audio server: PipeWire. The ALSA dev package has been renamed to libasound-dev (the old name libasound2-dev still works).

bash
sudo apt-get update
sudo apt-get install -y \
    portaudio19-dev libportaudio2 \
    ffmpeg libopus0 libopus-dev \
    libasound-dev \
    pulseaudio-utils \
    libxcb-xinerama0 libxkbcommon-x11-0 \
    build-essential python3-venv python3-pip

Ubuntu 20.04 ​

Note: Ubuntu 20.04 has Python 3.8 by default. You need to install Python 3.10+ first.

bash
# 1. Install Python 3.10+
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt-get update
sudo apt-get install -y python3.10 python3.10-venv python3.10-dev

# 2. Install audio dependencies (default audio server: PulseAudio)
sudo apt-get install -y \
    portaudio19-dev libportaudio2 \
    ffmpeg libopus0 libopus-dev \
    libasound2-dev \
    pulseaudio-utils \
    build-essential

Raspberry Pi OS (Bookworm / Debian 12) ​

The desktop edition has PipeWire pre-installed. The Lite edition requires manual installation of an audio server.

bash
sudo apt-get update

# Desktop edition: PipeWire is pre-installed, only need dev dependencies
sudo apt-get install -y \
    portaudio19-dev libportaudio2 \
    ffmpeg libopus0 libopus-dev \
    libasound-dev \
    pulseaudio-utils \
    build-essential python3-venv python3-pip

# Lite edition (no desktop): additionally install audio server:
# sudo apt-get install -y pipewire pipewire-pulse wireplumber

For Raspberry Pi, it's recommended to use a USB sound card. The built-in 3.5mm audio jack has poor quality and high latency.

Audio Permissions ​

bash
sudo usermod -a -G audio $USER
# Takes effect after re-login

Audio Verification ​

bash
# Check audio server
pactl info | grep "Server Name"
# Expected output:
#   PulseAudio → "Server Name: pulseaudio"
#   PipeWire   → "Server Name: PulseAudio (on PipeWire x.x.x)"

# Check sound card devices
aplay -l           # List output devices
arecord -l         # List input devices

# Check PortAudio
python3 -c "import sounddevice; print(sounddevice.query_devices())"

Important: Do NOT install the pulseaudio daemon package on PipeWire systems (Ubuntu 22.04+), as this will conflict with PipeWire. Only install pulseaudio-utils (which provides the pactl command).

Python Environment Setup ​

uv is a modern Python package manager that is fast and manages virtual environments automatically.

Install uv:

bash
# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Install project dependencies:

bash
uv sync

Run the project:

bash
uv run python main.py

Method 2: pip + venv ​

bash
# Create virtual environment
python3 -m venv .venv

# Activate virtual environment
source .venv/bin/activate      # Linux/macOS
# .venv\Scripts\activate       # Windows

# Install dependencies
pip install -r requirements.txt

Method 3: Conda (Optional) ​

Only use when special C++ dependencies (e.g., CUDA/MKL) are needed

bash
# Create environment
conda create -n py-xiaozhi python=3.10 -y
conda activate py-xiaozhi

# Install dependencies
pip install -r requirements.txt

Verify Installation ​

bash
# Using uv
uv run python -c "from PySide6.QtCore import qVersion; print('PySide6:', qVersion())"
uv run python -c "import sounddevice; print('SoundDevice OK')"
uv run python -c "import opuslib; print('Opus OK')"
uv run python -c "import sherpa_onnx; print('sherpa-onnx OK')"

# Using pip/venv
python -c "from PySide6.QtCore import qVersion; print('PySide6:', qVersion())"
python -c "import sounddevice; print('SoundDevice OK')"

Troubleshooting ​

SoundDevice Installation Failure ​

bash
# Ubuntu 20.04 / 22.04
sudo apt-get install -y portaudio19-dev libasound2-dev libportaudio2

# Ubuntu 24.04+
sudo apt-get install -y portaudio19-dev libasound-dev libportaudio2

# macOS
brew install portaudio

Audio Device Not Found (Linux) ​

Common on Raspberry Pi or service auto-start scenarios. PortAudio initializes before the audio service is ready, resulting in an empty device list.

bash
# 1. Confirm audio service is running
pactl info

# 2. If pactl reports an error, check the audio service
systemctl --user status pipewire pipewire-pulse  # PipeWire system
systemctl --user status pulseaudio               # PulseAudio system

# 3. If aplay -l shows devices but Python doesn't see them, restart audio service
systemctl --user restart pipewire pipewire-pulse wireplumber

# 4. Raspberry Pi Lite: may need to manually install audio server
sudo apt-get install -y pipewire pipewire-pulse wireplumber
systemctl --user enable pipewire pipewire-pulse wireplumber
systemctl --user start pipewire pipewire-pulse wireplumber

PulseAudio and PipeWire Conflict ​

If you installed the pulseaudio daemon by mistake, causing audio issues:

bash
# Remove PulseAudio daemon (keep pactl tools)
sudo apt-get remove -y pulseaudio
sudo apt-get install -y pulseaudio-utils  # Only install CLI tools

# Restart PipeWire
systemctl --user restart pipewire pipewire-pulse wireplumber

sherpa-onnx Import Failure (macOS) ​

sherpa-onnx requires the onnxruntime shared library, which may be missing on macOS:

bash
# Download onnxruntime
cd /tmp
curl -sL "https://github.com/microsoft/onnxruntime/releases/download/v1.17.1/onnxruntime-osx-arm64-1.17.1.tgz" -o onnxruntime.tgz
tar -xzf onnxruntime.tgz

# Copy shared library to sherpa_onnx
cp onnxruntime-osx-arm64-1.17.1/lib/libonnxruntime.1.17.1.dylib \
   .venv/lib/python3.10/site-packages/sherpa_onnx/lib/

Opus Library Missing ​

bash
# macOS
brew install opus

# Linux
sudo apt-get install -y libopus0 libopus-dev

PySide6 Display Issues (Linux) ​

bash
# Install Qt runtime libraries
sudo apt-get install -y libxcb-xinerama0 libxkbcommon-x11-0 libegl1

Package Manager Mirror Setup (for users in mainland China) ​

pip Mirror ​

bash
pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/

uv Mirror ​

bash
# Set environment variable
export UV_INDEX_URL=https://mirrors.aliyun.com/pypi/simple/

# Or configure in pyproject.toml
# [tool.uv]
# index-url = "https://mirrors.aliyun.com/pypi/simple/"

Version Requirements ​

DependencyVersion
Python>= 3.10
PySide6>= 6.6.0
SoundDevice>= 0.4.4
FFmpeg>= 4.0
Opus>= 1.3
PortAudio>= 19.0

Notes ​

  1. Use uv whenever possible to manage dependencies -- it's fast and handles virtual environments automatically
  2. Python version: Must be >= 3.10; 3.9 and below are not supported
  3. System dependencies first: Install system dependencies (ffmpeg, opus, portaudio) before Python dependencies
  4. Don't mix package managers: Choose either uv or pip, not both
  5. macOS sherpa-onnx: You may need to manually copy the onnxruntime shared library on first run