Skip to main content
CosyVoice logoCosyVoice
Install guide · checked October 2026

How to Install CosyVoice 3 Locally (Windows, Linux, Docker, ComfyUI)

Step by step from the official QwenAudio/CosyVoice repository: Linux setup, model download, first run, web UI and Docker servers, plus what applies on Windows and in ComfyUI. Every command is copied from the official README or the tool's own repository.

Start the installSkip it — try online

Before you start

What the official repository expects. The README doesn't publish a minimum GPU memory or disk size, so plan to test on your own hardware.

  • Linux, Conda and Python 3.10

    The README installs into a Conda environment with Python 3.10 and uses apt or yum for system packages, so its steps are written for Linux.

    README: Install

  • An NVIDIA GPU with CUDA 12

    requirements.txt pulls PyTorch 2.3.1 from the CUDA 12.1 wheel index and installs GPU packages (onnxruntime-gpu, TensorRT) on Linux; the Docker commands run with --runtime=nvidia.

    QwenAudio/CosyVoice requirements.txt

  • Git with submodules

    Clone with --recursive: the repository pulls Matcha-TTS in as a submodule. git-lfs is needed if you fetch the optional ttsfrd resource.

    README: Install

  • Pick a model

    The README recommends Fun-CosyVoice3-0.5B for the best results; CosyVoice2-0.5B and the CosyVoice-300M family download the same way.

    Hugging Face: Fun-CosyVoice3-0.5B-2512

Install CosyVoice from GitHub (Linux)

Run these in order. The clone URL points at the repository's current home, github.com/QwenAudio/CosyVoice — the README still shows the old FunAudioLLM URL, which redirects there.

1. Clone and create the environment
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. Only if you hit sox errors
# If you encounter sox compatibility issues
# ubuntu
sudo apt-get install sox libsox-dev
# centos
sudo yum install sox sox-devel
3. Download the models (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')

Optional: the ttsfrd package improves text normalization. The README says this step isn't necessary — without it CosyVoice uses wetext — and the wheel is built for Linux x86_64 and Python 3.10. It needs the CosyVoice-ttsfrd resource, which the README downloads alongside the models.

4. Optional: install 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. First run: the official examples
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

Run the CosyVoice web UI

The repository ships a Gradio web demo, webui.py. This is the README command:

Start the web demo (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

The README's example points at CosyVoice-300M. webui.py loads whatever --model_dir points to with AutoModel, so you can try a folder you downloaded above, such as pretrained_models/Fun-CosyVoice3-0.5B; the README itself only documents the 300M models here.

Docker, gRPC and FastAPI servers

For a service, the README builds a Docker image from runtime/python and runs either a gRPC or a FastAPI server on port 50000. It documents building the image yourself; it doesn't list a prebuilt image.

Build and run the server (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>

For speed, the README documents vLLM for CosyVoice 2 and 3 (vLLM 0.11.x and later, or 0.9.0; older versions don't work and 0.10.x is untested) and a TensorRT-LLM runtime in runtime/triton_trtllm that it says gives CosyVoice 2's LLM about 4× the speed of the Hugging Face transformers implementation.

vLLM in a separate environment (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

Comparing self-hosting with a hosted API? See our CosyVoice API guide for Alibaba Cloud Model Studio models and official prices.

Installing CosyVoice on Windows

The official repository doesn't document a Windows install. This is what its own files show, so you know what to expect:

  • No official Windows steps

    The README install uses apt or yum for sox and a Linux-only ttsfrd wheel. Windows is not mentioned.

    README: Install

  • GPU packages are Linux-only

    requirements.txt installs the CPU build of onnxruntime on Windows and macOS, and only installs DeepSpeed, onnxruntime-gpu and TensorRT on Linux.

    QwenAudio/CosyVoice requirements.txt

  • Skip ttsfrd

    The optional ttsfrd wheel is built for Linux x86_64. Leave it out: the README says CosyVoice then falls back to wetext.

    README: Install

  • Or follow the Linux steps in WSL

    Windows Subsystem for Linux runs a Linux distribution on Windows, so the commands above apply as written. The CosyVoice docs don't cover WSL, so treat it as untested by the CosyVoice team.

    Microsoft: Install WSL

CosyVoice in ComfyUI

ComfyUI support comes from community custom nodes, not from the CosyVoice team. Facts below are from each node's own README.

  • FL CosyVoice3 (filliptm)

    Install it from ComfyUI Manager (search "FL CosyVoice3") or manually. It loads Fun-CosyVoice3-0.5B (recommended), CosyVoice2-0.5B or CosyVoice-300M, downloads them on first use to ComfyUI/models/cosyvoice/, and adds zero-shot, cross-lingual, voice conversion and dialog nodes. Its README recommends 3–30 seconds of reference audio and an NVIDIA GPU with 8 GB+ VRAM, with CPU and Mac MPS also supported.

    filliptm/ComfyUI_FL-CosyVoice3 (GitHub)

  • CosyVoice-ComfyUI (AIFSH)

    An older node for the original CosyVoice: its last commit is from September 2024, before CosyVoice2-0.5B was released. It downloads weights from ModelScope and needs ffmpeg.

    AIFSH/CosyVoice-ComfyUI (GitHub)

Manual install of FL CosyVoice3 (its README)
cd ComfyUI/custom_nodes
git clone https://github.com/filliptm/ComfyUI_FL-CosyVoice3.git
cd ComfyUI_FL-CosyVoice3
pip install -r requirements.txt

Common install errors

The repository's FAQ.md covers the two errors new installs hit most: a missing matcha module (the submodule didn't come down) and a missing ttsfrd resource.zip (git-lfs isn't installed).

Fixes from 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

Looking for cosyvoice.cpp? Community ports exist, such as a C/C++ inference project; they aren't maintained by the CosyVoice team, so check their own docs. Lourdle/cosyvoice.cpp (GitHub)

Don't want to install anything?

CosyVoice.org runs CosyVoice in your browser on hosted models — free to start, no GPU, no Python. If you need an API instead, Alibaba Cloud hosts CosyVoice models too.

Try CosyVoice free →Clone a voice online →Compare hosted APIs →

CosyVoice install FAQ

How do I install CosyVoice?

Clone github.com/QwenAudio/CosyVoice with --recursive, create a Conda environment with Python 3.10, run pip install -r requirements.txt, download Fun-CosyVoice3-0.5B with the ModelScope or Hugging Face SDK, then run python example.py. That is the path the official README documents, on Linux.

Does CosyVoice run on Windows?

There are no official Windows instructions. requirements.txt has a Windows branch (CPU onnxruntime), but the GPU packages and the optional ttsfrd wheel are Linux-only. The practical options are WSL, a ComfyUI node, or the hosted version in your browser.

Is there a CosyVoice Docker image?

The README builds one: docker build in runtime/python, then docker run with a gRPC or FastAPI server on port 50000 using an NVIDIA runtime. It does not document a prebuilt image.

How do I use CosyVoice in ComfyUI?

Install a community custom node. FL CosyVoice3 (filliptm/ComfyUI_FL-CosyVoice3) is in ComfyUI Manager, supports Fun-CosyVoice3-0.5B and CosyVoice2-0.5B, and downloads the models on first use. It is not an official CosyVoice project.

Where is the CosyVoice GitHub repository?

github.com/QwenAudio/CosyVoice. The old address, github.com/FunAudioLLM/CosyVoice, redirects there. The model weights are on Hugging Face (FunAudioLLM) and ModelScope.

What GPU do I need for CosyVoice 3?

The official README and model card don't state a minimum. requirements.txt targets CUDA 12.1 builds of PyTorch, and the third-party FL CosyVoice3 node recommends 8 GB+ of VRAM. Test with your own hardware, or use the hosted version if you don't have a GPU.

Sources

Facts on this page were checked against these official sources on October 26, 2026.