🛠️ CosyVoice: From Zero to Voice Cloning in 10 Minutes

This guide walks you through deploying CosyVoice with Docker, running your first inference, and cloning a voice — all under 10 minutes if you have a GPU machine.

⏱ Estimated time: 8-10 minutes on GPU, 30 minutes on CPU (inference will be slower).

📋 Prerequisites

• 🔹 Docker — docker --version should return 24+


• 🔹 RAM: 4GB minimum, 8GB recommended


• 🔹 GPU: NVIDIA GPU with 6GB+ VRAM strongly recommended (CPU works but is slow)


• 🔹 Storage: 10GB free (the Docker image is ~7GB)


• 🔹 ⏱ Time: ~10 minutes for full setup

🚀 Step-by-Step

Step 1️⃣ — Pull the Image

docker pull neosun/cosyvoice:latest

The image is ~7GB. On a 100Mbps connection this takes about 10 minutes. Grab a coffee.

Step 2️⃣ — Write docker-compose.yml

version: '3.8'
services:
  cosyvoice:
    image: neosun/cosyvoice:latest
    restart: unless-stopped
    ports:
      - "5000:5000"
    volumes:
      - ./data/cosyvoice:/data
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]

📖 Note: neosun/cosyvoice exposes port 5000 (not 8080 like the official docs). The volume mounts for model storage but isn't strictly required.

Step 3️⃣ — Start the Service

docker compose up -d
docker compose logs -f

Watch the logs for Uvicorn running on http://0.0.0.0:5000 — that means the server is ready. On first start, models are loaded into memory, which takes 30-60 seconds.

Step 4️⃣ — Verify the API

curl -s http://localhost:5000/ | python3 -m json.tool

If you see a JSON response with endpoint info, it's working. If you get connection refused, wait 30 more seconds.

Step 5️⃣ — Clone Your First Voice

Prepare a short WAV file (3-10 seconds, 16kHz mono recommended). Then:

curl -X POST http://localhost:5000/inference \
  -F "audio=@sample.wav" \
  -F "text=Hello, this is my cloned voice speaking English." \
  -F "language=en" \
  -o output.wav

If everything works, you'll get an output.wav file with the cloned voice speaking your text. The first inference is slower (model warmup) — subsequent calls are faster.

⚠️ Troubleshooting

🚫 Port 5000 already in use

macOS Monterey uses port 5000 for AirPlay receiver. Change the compose port mapping to "5001:5000" — it won't affect CosyVoice internally.

🐢 Very slow inference

You're likely running on CPU. CosyVoice needs GPU for real-time performance. If you don't have a GPU, the inference will take 30-60 seconds per utterance instead of 1-3 seconds.

💥 Container crashes on start

Usually a GPU/driver issue. Run docker run --gpus all nvidia/cuda:12.2.0-base nvidia-smi to verify your GPU is accessible from Docker. If it fails, install nvidia-container-toolkit.

📊 Real Performance Numbers

Tested on: RTX 3060 12GB, 6-core CPU, 32GB RAM, SSD storage

🏁 Done!

You now have a fully functional CosyVoice instance capable of multilingual TTS and voice cloning. Start with short, clean audio samples and experiment with the emotion controls — that's where CosyVoice really shines over other open TTS models.