安装教程 · 2026 年 10 月核对

如何在本地安装 CosyVoice 3（Windows、Linux、Docker、ComfyUI）

按官方仓库 QwenAudio/CosyVoice 一步步来：Linux 环境、模型下载、首次运行、Web UI 和 Docker 服务，以及 Windows 和 ComfyUI 上需要注意什么。所有命令都摘自官方 README 或相应工具自己的仓库。

开始安装不想装？直接在线用

准备工作

官方仓库的要求如下。README 没有给出最低显存或磁盘空间，请在自己的硬件上实测。

Linux、Conda 和 Python 3.10
README 在 Python 3.10 的 Conda 环境中安装，并用 apt 或 yum 安装系统包，所以步骤是按 Linux 写的。
README: Install
支持 CUDA 12 的 NVIDIA 显卡
requirements.txt 从 CUDA 12.1 的 wheel 源安装 PyTorch 2.3.1，并在 Linux 上安装 GPU 相关包（onnxruntime-gpu、TensorRT）；Docker 命令使用 --runtime=nvidia。
QwenAudio/CosyVoice requirements.txt
支持子模块的 Git
用 --recursive 克隆：仓库以子模块形式引入 Matcha-TTS。如果要下载可选的 ttsfrd 资源，还需要 git-lfs。
README: Install
选一个模型
README 推荐效果最好的 Fun-CosyVoice3-0.5B；CosyVoice2-0.5B 和 CosyVoice-300M 系列的下载方式相同。
Hugging Face: Fun-CosyVoice3-0.5B-2512

从 GitHub 安装 CosyVoice（Linux）

按顺序执行。克隆地址用的是仓库现在的地址 github.com/QwenAudio/CosyVoice —— README 里仍写着旧的 FunAudioLLM 地址，它会自动跳转过来。

1. 克隆仓库并创建环境

git clone --recursive https://github.com/QwenAudio/CosyVoice.git
cd CosyVoice
git submodule update --init --recursive
conda create -n cosyvoice -y python=3.10
conda activate cosyvoice
pip install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host=mirrors.aliyun.com

2. 仅在遇到 sox 报错时执行

# If you encounter sox compatibility issues
# ubuntu
sudo apt-get install sox libsox-dev
# centos
sudo yum install sox sox-devel

3. 下载模型（Python）

# modelscope SDK model download
from modelscope import snapshot_download
snapshot_download('FunAudioLLM/Fun-CosyVoice3-0.5B-2512', local_dir='pretrained_models/Fun-CosyVoice3-0.5B')
snapshot_download('iic/CosyVoice2-0.5B', local_dir='pretrained_models/CosyVoice2-0.5B')
snapshot_download('iic/CosyVoice-ttsfrd', local_dir='pretrained_models/CosyVoice-ttsfrd')

# for oversea users, huggingface SDK model download
from huggingface_hub import snapshot_download
snapshot_download('FunAudioLLM/Fun-CosyVoice3-0.5B-2512', local_dir='pretrained_models/Fun-CosyVoice3-0.5B')
snapshot_download('FunAudioLLM/CosyVoice2-0.5B', local_dir='pretrained_models/CosyVoice2-0.5B')
snapshot_download('FunAudioLLM/CosyVoice-ttsfrd', local_dir='pretrained_models/CosyVoice-ttsfrd')

可选：ttsfrd 包能改进文本正则化。README 说这一步不是必需的 —— 不装时 CosyVoice 默认使用 wetext —— 而且它的 wheel 只适用于 Linux x86_64 和 Python 3.10。它需要 CosyVoice-ttsfrd 资源，README 会和模型一起下载。

4. 可选：安装 ttsfrd

cd pretrained_models/CosyVoice-ttsfrd/
unzip resource.zip -d .
pip install ttsfrd_dependency-0.1-py3-none-any.whl
pip install ttsfrd-0.4.2-cp310-cp310-linux_x86_64.whl

5. 首次运行：官方示例

python example.py

# example.py, cosyvoice3_example():
cosyvoice = AutoModel(model_dir='pretrained_models/Fun-CosyVoice3-0.5B')
# zero_shot usage
for i, j in enumerate(cosyvoice.inference_zero_shot('八百标兵奔北坡，北坡炮兵并排跑，炮兵怕把标兵碰，标兵怕碰炮兵炮。', 'You are a helpful assistant.<|endofprompt|>希望你以后能够做的比我还好呦。',
                                                    './asset/zero_shot_prompt.wav', stream=False)):
    torchaudio.save('zero_shot_{}.wav'.format(i), j['tts_speech'], cosyvoice.sample_rate)

README: Install QwenAudio/CosyVoice example.py

运行 CosyVoice Web UI

仓库自带一个 Gradio 网页演示 webui.py。README 中的命令如下：

启动网页演示（README）

# change iic/CosyVoice-300M-SFT for sft inference, or iic/CosyVoice-300M-Instruct for instruct inference
python3 webui.py --port 50000 --model_dir pretrained_models/CosyVoice-300M

README 的示例指向 CosyVoice-300M。webui.py 会用 AutoModel 加载 --model_dir 指向的目录，所以你可以试试上面下载的目录，比如 pretrained_models/Fun-CosyVoice3-0.5B；不过 README 在这里只写了 300M 系列模型。

Docker、gRPC 与 FastAPI 服务

如果要部署成服务，README 会从 runtime/python 构建 Docker 镜像，再在 50000 端口运行 gRPC 或 FastAPI 服务。文档写的是自己构建镜像，没有列出现成的镜像。

构建并运行服务（README）

cd runtime/python
docker build -t cosyvoice:v1.0 .
# change iic/CosyVoice-300M to iic/CosyVoice-300M-Instruct if you want to use instruct inference
# for grpc usage
docker run -d --runtime=nvidia -p 50000:50000 cosyvoice:v1.0 /bin/bash -c "cd /opt/CosyVoice/CosyVoice/runtime/python/grpc && python3 server.py --port 50000 --max_conc 4 --model_dir iic/CosyVoice-300M && sleep infinity"
cd grpc && python3 client.py --port 50000 --mode <sft|zero_shot|cross_lingual|instruct>
# for fastapi usage
docker run -d --runtime=nvidia -p 50000:50000 cosyvoice:v1.0 /bin/bash -c "cd /opt/CosyVoice/CosyVoice/runtime/python/fastapi && python3 server.py --port 50000 --model_dir iic/CosyVoice-300M && sleep infinity"
cd fastapi && python3 client.py --port 50000 --mode <sft|zero_shot|cross_lingual|instruct>

想要更快，README 为 CosyVoice 2 和 3 提供了 vLLM 支持（vLLM 0.11.x 及以上或 0.9.0；更早的版本不能用，0.10.x 未测试），以及 runtime/triton_trtllm 中的 TensorRT-LLM 运行时，称其让 CosyVoice 2 的 LLM 比 Hugging Face transformers 实现快约 4 倍。

在独立环境中使用 vLLM（README）

conda create -n cosyvoice_vllm --clone cosyvoice
conda activate cosyvoice_vllm
# for vllm>=0.11.0
pip install vllm==v0.11.0 transformers==4.57.1 numpy==1.26.4 -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host=mirrors.aliyun.com
python vllm_example.py

在自部署和托管 API 之间犹豫？阿里云百炼的模型和官方价格见我们的CosyVoice API 指南。

在 Windows 上安装 CosyVoice

官方仓库没有提供 Windows 安装说明。下面是从仓库文件本身能看到的情况，方便你心里有数：

没有官方的 Windows 步骤
README 的安装用 apt 或 yum 安装 sox，以及只支持 Linux 的 ttsfrd wheel，没有提到 Windows。
README: Install
GPU 相关包只装在 Linux 上
requirements.txt 在 Windows 和 macOS 上安装 CPU 版 onnxruntime，DeepSpeed、onnxruntime-gpu 和 TensorRT 只在 Linux 上安装。
QwenAudio/CosyVoice requirements.txt
跳过 ttsfrd
可选的 ttsfrd wheel 只适用于 Linux x86_64。不装即可：README 说此时 CosyVoice 会改用 wetext。
README: Install
或者在 WSL 里按 Linux 步骤安装
适用于 Linux 的 Windows 子系统（WSL）可以在 Windows 上运行 Linux 发行版，上面的命令可以照用。CosyVoice 文档没有涉及 WSL，请视为 CosyVoice 团队未测试过的方式。
Microsoft: Install WSL

在 ComfyUI 中使用 CosyVoice

ComfyUI 支持来自社区的自定义节点，不是 CosyVoice 团队开发的。以下信息均来自各节点自己的 README。

FL CosyVoice3（filliptm）
可以在 ComfyUI Manager 中搜索“FL CosyVoice3”安装，也可以手动安装。它支持 Fun-CosyVoice3-0.5B（推荐）、CosyVoice2-0.5B 和 CosyVoice-300M，首次使用时自动下载到 ComfyUI/models/cosyvoice/，提供零样本、跨语言、声音转换和多人对话等节点。它的 README 建议使用 3–30 秒参考音频和 8 GB 以上显存的 NVIDIA 显卡，也支持 CPU 和 Mac MPS。
filliptm/ComfyUI_FL-CosyVoice3 (GitHub)
CosyVoice-ComfyUI（AIFSH）
一个面向初代 CosyVoice 的旧节点：最后一次提交在 2024 年 9 月，早于 CosyVoice2-0.5B 发布。它从 ModelScope 下载权重，需要 ffmpeg。
AIFSH/CosyVoice-ComfyUI (GitHub)

手动安装 FL CosyVoice3（摘自其 README）

cd ComfyUI/custom_nodes
git clone https://github.com/filliptm/ComfyUI_FL-CosyVoice3.git
cd ComfyUI_FL-CosyVoice3
pip install -r requirements.txt

常见安装报错

仓库的 FAQ.md 覆盖了新安装最常遇到的两个错误：找不到 matcha 模块（子模块没有下载下来），以及找不到 ttsfrd 的 resource.zip（没有安装 git-lfs）。

FAQ.md 中的解决方法

# ModuleNotFoundError: No module named 'matcha'
git submodule update --init --recursive
export PYTHONPATH=third_party/Matcha-TTS

# cannot find resource.zip or cannot unzip resource.zip (install git-lfs first)
git clone https://www.modelscope.cn/iic/CosyVoice-ttsfrd.git pretrained_models/CosyVoice-ttsfrd

QwenAudio/CosyVoice FAQ.md

在找 cosyvoice.cpp？社区里有一些移植项目，比如一个 C/C++ 推理实现；它们不由 CosyVoice 团队维护，请以各自的文档为准。 Lourdle/cosyvoice.cpp (GitHub)

不想安装？

CosyVoice.org 在浏览器里用托管模型运行 CosyVoice —— 免费开始，不需要 GPU，也不需要 Python。如果你需要 API，阿里云也提供托管的 CosyVoice 模型。

免费试用 CosyVoice →在线克隆声音 →对比托管 API →

CosyVoice 安装常见问题

如何安装 CosyVoice？

用 --recursive 克隆 github.com/QwenAudio/CosyVoice，创建 Python 3.10 的 Conda 环境，执行 pip install -r requirements.txt，用 ModelScope 或 Hugging Face SDK 下载 Fun-CosyVoice3-0.5B，然后运行 python example.py。这就是官方 README 在 Linux 上的安装流程。

CosyVoice 能在 Windows 上运行吗？

没有官方的 Windows 安装说明。requirements.txt 有 Windows 分支（CPU 版 onnxruntime），但 GPU 相关包和可选的 ttsfrd wheel 只支持 Linux。可行的办法是 WSL、ComfyUI 节点，或者直接在浏览器里用托管版。

有 CosyVoice 的 Docker 镜像吗？

README 是自己构建：在 runtime/python 里 docker build，再用 NVIDIA 运行时 docker run，在 50000 端口启动 gRPC 或 FastAPI 服务。文档没有提供现成的镜像。

怎么在 ComfyUI 里用 CosyVoice？

安装社区自定义节点。FL CosyVoice3（filliptm/ComfyUI_FL-CosyVoice3）可在 ComfyUI Manager 中找到，支持 Fun-CosyVoice3-0.5B 和 CosyVoice2-0.5B，首次使用时自动下载模型。它不是 CosyVoice 官方项目。

CosyVoice 的 GitHub 仓库在哪？

github.com/QwenAudio/CosyVoice。旧地址 github.com/FunAudioLLM/CosyVoice 会跳转过去。模型权重在 Hugging Face（FunAudioLLM）和 ModelScope 上。

CosyVoice 3 需要什么显卡？

官方 README 和模型卡没有给出最低要求。requirements.txt 面向 CUDA 12.1 版的 PyTorch，第三方的 FL CosyVoice3 节点建议 8 GB 以上显存。请在自己的硬件上实测；没有显卡可以用托管版。

资料来源

本页事实已于 2026 年 10 月 26 日对照以下官方资料核对。

如何在本地安装 CosyVoice 3（Windows、Linux、Docker、ComfyUI）

准备工作

Linux、Conda 和 Python 3.10

支持 CUDA 12 的 NVIDIA 显卡

支持子模块的 Git

选一个模型