Skip to main content
Install guide · checked November 2026

How to Install CosyVoice 3 from GitHub (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.

CosyVoice GitHub repo (QwenAudio/CosyVoice)

The official CosyVoice code lives at github.com/QwenAudio/CosyVoice. It moved there from FunAudioLLM/CosyVoice; the old URL redirects to the new one, but the README still shows the old clone address.

Clone the repo and its submodule
git clone --recursive https://github.com/QwenAudio/CosyVoice.git
cd CosyVoice
# If you failed to clone the submodule due to network failures, run this until it succeeds
git submodule update --init --recursive

    QwenAudio/CosyVoice READMEHugging Face: Fun-CosyVoice3-0.5B-2512ModelScope: Fun-CosyVoice3-0.5B-2512

    New to the model? Read CosyVoice3 (CosyVoice 3) explained for the versions, sizes and the open vs hosted split.

    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

    Download the models from Hugging Face (or ModelScope)

    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)

    ComfyUI: install FL CosyVoice3

    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.