Qwen3-TTS Local Setup: Voice Cloning and Voice Design on Your Own GPU

Short answer: pip install -U qwen-tts, download Qwen3-TTS-12Hz-1.7B-CustomVoice (3.9GB) plus the 12Hz tokenizer (0.68GB) from Hugging Face, and you have Apache 2.0 text-to-speech with 3-second voice cloning, description-based voice design, and 10 languages running on a single CUDA GPU — an 8GB card is a comfortable floor for the 1.7B model, and there is a 0.6B variant (1.8GB) for smaller cards. The catch: it is CUDA-only. No official CPU or Apple Silicon path exists as of August 2026.

Alibaba's Qwen team open-sourced the Qwen3-TTS family on January 22, 2026, and it moved fast even by Qwen standards: 12,800 GitHub stars, and the 1.7B base model alone pulling over 2.5 million Hugging Face downloads in the past 30 days (GitHub API / Hugging Face download counters, August 2026). The reason is simple — this is the first Apache 2.0 model that bundles serious voice cloning and voice design in one package. Simon Willison put it well the day it dropped: "voice cloning is now something that's available to anyone with a GPU and a few GBs of VRAM... or in this case a web browser that can access Hugging Face."

This guide covers the actual local install — package, weights, both download paths, cloning, design — plus the honest limitations Qwen's README doesn't advertise.

---

What Qwen3-TTS Is: Six Checkpoints, Three Jobs {#what-it-is}

Answer first: two sizes (0.6B and 1.7B) times three variants — Base for voice cloning, CustomVoice for nine ready-made speakers, VoiceDesign (1.7B only) for creating voices from text descriptions. All Apache 2.0, all needing the same 0.68GB tokenizer.

The full family, with disk sizes measured from the Hugging Face file listings (August 2026):

The "12Hz" in every name is the frame rate of the speech tokenizer — 12.5 frames per second of audio per the tokenizer config, with 24kHz output; Qwen's benchmark tables mention 25Hz variants, but those were never released. Supported languages, per the model card: Chinese, English, Japanese, Korean, German, French, Russian, Portuguese, Spanish, and Italian. The CustomVoice speakers skew Chinese (Vivian, Serena, Uncle_Fu, Dylan, Eric) with two English voices (Ryan, Aiden), one Japanese (Ono_Anna), and one Korean (Sohee).

Qwen also claims streaming synthesis with "end-to-end synthesis latency as low as 97ms" — a vendor number with no stated test hardware, so treat it as a ceiling-case figure, not a promise for your GPU.

If you already run Qwen text models locally (our Qwen 3.6 27B guide covers the current flagship), the TTS family will feel familiar: same Hugging Face organization, same Apache licensing, same fast-iteration culture.

---

Hardware Requirements: The Honest Version {#hardware}

Answer first: plan on a CUDA GPU with 8GB VRAM for the 1.7B models and ~4GB for the 0.6B — our estimate from checkpoint sizes, because Qwen publishes no official VRAM figures. No CPU, no Apple Silicon, no ROCm in the official repo.

Here is what is actually documented versus what we can infer:

• Documented: every official example loads with device_map="cuda:0" and dtype=torch.bfloat16. The README recommends FlashAttention 2 "to reduce GPU memory usage." That is the entire official hardware story.
• Inferred (ours): the model safetensors are 3.83GB (1.7B) or 1.81GB (0.6B) in bf16, plus the 0.68GB codec, plus activations and the KV cache during generation. Roughly 6-8GB free VRAM for 1.7B and ~4GB for 0.6B is the realistic envelope.
• Turing cards are trouble. Repo issue #43 documents CUDA device-side asserts on an RTX 2060 in FP16 — the model NaNs during generation on pre-Ampere silicon, and the reporter found only full FP32 stable, which doubles the memory bill. Treat RTX 30-series or newer as the practical floor.
• Not supported: CPU-only inference, Apple Silicon/MPS, and ROCm have no official path as of August 2026. Mac users: the free official Hugging Face Space demo (2.1k likes) covers one-off jobs, and the community mlx-audio library has added unofficial Qwen3-TTS support — Simon Willison documented running voice design through it on a Mac.

Any 8GB-class card that handles small Qwen LLMs handles this — our best Qwen models for 8GB VRAM page maps that hardware tier. If your GPU is below that, the 0.6B variants are the honest fallback, at a real quality cost in cloning fidelity.

---

Install and First Run {#install}

Answer first: one pip package, two downloads, one command for a web UI. Ten minutes on a decent connection.

All commands below are from the official README (QwenLM/Qwen3-TTS, checked August 2026).

1. Install the package (fresh venv recommended; package metadata allows Python 3.9+):

pip install -U qwen-tts

Optionally add FlashAttention 2 — worth it for VRAM savings:

pip install -U flash-attn --no-build-isolation
# If your machine has <96GB RAM and many cores, cap build jobs:
# MAX_JOBS=4 pip install -U flash-attn --no-build-isolation

2. Download weights. Qwen's docs lean ModelScope (their China-side hub), but Hugging Face works identically — pick one:

# Hugging Face
huggingface-cli download Qwen/Qwen3-TTS-Tokenizer-12Hz --local-dir ./Qwen3-TTS-Tokenizer-12Hz
huggingface-cli download Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice --local-dir ./Qwen3-TTS-12Hz-1.7B-CustomVoice

# ModelScope (mainland China)
modelscope download --model Qwen/Qwen3-TTS-Tokenizer-12Hz --local_dir ./Qwen3-TTS-Tokenizer-12Hz
modelscope download --model Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice --local_dir ./Qwen3-TTS-12Hz-1.7B-CustomVoice

You can also skip manual downloads entirely — from_pretrained("Qwen/...") pulls weights on first run.

3. Easiest first run — the bundled web UI:

qwen-tts-demo Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice --ip 0.0.0.0 --port 8000

Open port 8000 and you get a browser interface for the nine stock speakers. (For the Base model's microphone-based cloning, the demo needs HTTPS — the README documents --ssl-certfile/--ssl-keyfile flags.)

4. Or generate from Python:

from qwen_tts import Qwen3TTSModel
import torch

model = Qwen3TTSModel.from_pretrained(
    "Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice",
    device_map="cuda:0",
    dtype=torch.bfloat16,
    attn_implementation="flash_attention_2",
)

wavs, sr = model.generate_custom_voice(
    text="Local text-to-speech finally caught up with the cloud.",
    language="English",
    speaker="Ryan",
    instruct="Speak with calm confidence, medium pace.",
)

The instruct parameter is the underrated feature here: plain-language control of tone, pace, and emotion per generation, no SSML tags.

For serving at scale, vLLM shipped day-0 Qwen3-TTS support via vLLM-Omni — offline (batch) inference only for now, per the README, with online serving still pending.

---

Voice Cloning: 3 Seconds of Reference Audio {#voice-cloning}

Answer first: give the Base model a short reference clip plus its transcript, and it speaks any text in that voice — Qwen's headline claim is cloning from as little as 3 seconds of audio.

model = Qwen3TTSModel.from_pretrained(
    "Qwen/Qwen3-TTS-12Hz-1.7B-Base",
    device_map="cuda:0",
    dtype=torch.bfloat16,
    attn_implementation="flash_attention_2",
)

wavs, sr = model.generate_voice_clone(
    text="This is my cloned voice reading a sentence it has never heard.",
    language="English",
    ref_audio="my_reference.wav",   # a few seconds of clean speech
    ref_text="Exact transcript of the reference clip.",
)

Practical notes from the model card:

• The transcript matters. ref_text should match the reference audio exactly — the model aligns text to audio to learn the voice.
• There is an x_vector_only_mode that clones from a speaker embedding alone, without a transcript, but the card warns "cloning quality may be reduced." Use it only when transcription is impossible.
• Cross-lingual cloning works: an English reference can drive Chinese output and vice versa, within the 10 supported languages.

Three seconds is genuinely enough to be recognizable; a clean 10-30 second clip is noticeably better. And the standard warning applies with more force than ever: Apache 2.0 licenses the software. Cloning a real person's voice without consent can violate impersonation and publicity laws regardless of the model's license. Our local voice cloning overview covers the landscape — and where the legal lines sit.

The commercial-license angle deserves one more sentence, because it is the reason this model displaced XTTS v2 as the default recommendation: XTTS ships under Coqui's non-commercial CPML, so every commercial XTTS deployment needed a paid license. Qwen3-TTS removes that entire problem.

---

Voice Design: Describe a Voice Into Existence {#voice-design}

Answer first: the 1.7B-VoiceDesign checkpoint builds a voice from a text description — age, timbre, attitude, pacing — no reference audio at all. No 0.6B version exists.

model = Qwen3TTSModel.from_pretrained(
    "Qwen/Qwen3-TTS-12Hz-1.7B-VoiceDesign",
    device_map="cuda:0",
    dtype=torch.bfloat16,
)

wavs, sr = model.generate_voice_design(
    text="Welcome back to the show. Today we are going deep on local AI.",
    language="English",
    instruct="A warm, gravelly male radio host in his 50s, unhurried, slight smile in the voice.",
)

This is the feature with no real open-weights precedent at this quality level. For audiobook and podcast work it means casting characters by writing casting notes — a distinct narrator, a skeptical interviewer, a child character — without hunting for reference clips for each one. It pairs naturally with the pipeline in our best local TTS models roundup if you are building narration workflows.

The trade-off: design output is less predictable than CustomVoice's tuned speakers. Expect to iterate on the description a few times per voice, and pin the seed once you like one.

---

Benchmarks: Good, Not Uncontested {#benchmarks}

Answer first: on Qwen's own SEED-TTS test-set numbers, Qwen3-TTS-1.7B-Base leads the open field on English WER (1.24) and speaker similarity, but CosyVoice 3 still edges it on Chinese. These are vendor-run figures — read them as "top tier," not "undisputed champion."

Word error rate of re-transcribed output (lower = the TTS spoke more accurately), as reported in the Qwen3-TTS README (SEED-TTS test set):

Source: QwenLM/Qwen3-TTS README benchmark tables, retrieved August 2026. Vendor-reported.

Two honest readings. First, Qwen publishing a table where a competitor (CosyVoice 3, also Alibaba-adjacent) beats its Chinese number is a small credibility signal — this is not a cherry-picked chart. Second, the gap over F5-TTS — the previous open cloning favorite — is meaningful on both languages, and Qwen's reported speaker-similarity scores (0.799 Chinese / 0.775 English cosine similarity) point the same direction: clones that hold the voice consistently across long passages.

What no benchmark table captures: CustomVoice's instruct control and VoiceDesign have no equivalent in most of the compared systems at all.

---

Qwen3-TTS vs Kokoro: The Question Everyone Asks {#vs-kokoro}

Answer first: Kokoro for narration in a stock voice on any hardware; Qwen3-TTS the moment you need cloning, voice design, or instruction control. Kokoro cannot clone voices at all — by deliberate design.

Sources: Qwen3-TTS and Kokoro-82M model cards, August 2026.

The size gap is the whole story. Kokoro fits its 82M parameters into environments where Qwen3-TTS cannot even load — CPU-only servers, small VPS boxes, Raspberry Pi-class hardware — and its stock voices are excellent for the audiobook/narration use case. Our Kokoro setup guide gets it running in minutes. But Kokoro has no cloning mechanism at all — its voices are fixed, prepackaged style vectors — and it has no analogue to voice design or per-generation instructions.

So the honest decision rule: if the built-in voices are good enough, run Kokoro and bank the VRAM. If the product is the voice — cloned, designed, or directed — Qwen3-TTS is now the default open-weights answer. For the wider field (XTTS, Chatterbox, and friends), see our Kokoro vs XTTS vs Chatterbox comparison.

---

Honest Limitations {#limitations}

Answer first: CUDA-only, no official VRAM documentation, a known memory-leak issue under sustained load, and a repo that has been quiet since March 2026. Excellent model, young tooling.

• CUDA-only. No CPU, MPS/Apple Silicon, or ROCm support in the official repo. This is the hardest wall: Mac-based creators are limited to the hosted Space demo. Piper remains the CPU-first alternative for narration.
• No official VRAM or throughput numbers. Everything in our hardware section is inference from checkpoint sizes and community reports, because Qwen documents nothing. The "97ms" streaming latency is a vendor claim with unstated hardware.
• Memory behavior under load. GitHub issue #242 reported a runaway memory leak after many consecutive generations, and #263 unstable cloning through the vLLM path — both since closed, but they are recent enough that batch-job authors should still recycle the process periodically on long runs and pin package versions.
• Repo momentum has cooled. Last push March 17, 2026 (GitHub API). The 25Hz variants teased in the benchmark tables never shipped, and vLLM online serving is still "future work." Qwen ships in waves, so this likely means the team moved to the next version — but buy the model that exists, not the roadmap.
• English voice selection is thin in CustomVoice. Two of nine stock speakers are English. Cloning and VoiceDesign close the gap, but Kokoro's English voice library is far deeper out of the box.
• Quality floor on 0.6B. The small variants load on ~4GB cards, but Qwen positions 1.7B as the higher-quality tier and its benchmark tables are built on it. If cloning is the point, find the VRAM for the bigger model.

---

Verdict {#verdict}

Qwen3-TTS is the current default answer for local voice cloning and voice design — the first time both live in one Apache 2.0 package — provided you have a CUDA GPU with ~8GB of VRAM.

1. Have an 8GB+ NVIDIA card and want cloning or custom voices? Install it today: pip install -U qwen-tts, pull 1.7B-CustomVoice first (~4.5GB with the tokenizer), add Base later if you want cloning (~3.9GB more).
2. Just need narration in a good stock voice? Kokoro is 20x smaller, runs anywhere, and is still the better pure-narration tool.
3. On a Mac or CPU-only? Use the official Hugging Face Space for occasional jobs; run Kokoro or Piper locally for production narration. Wait on Qwen3-TTS until a community MPS/ONNX port matures.
4. Commercial project? This is the one: Apache 2.0 removes the licensing shadow that hangs over XTTS v2 deployments.

The bigger picture: 2.5M+ downloads a month says local TTS crossed a line. Voice cloning that used to require a paid API — or a legally awkward model — is now a pip install on mid-range gaming hardware.

---

Sources {#sources}

• QwenLM/Qwen3-TTS — official repo: install commands, benchmark tables, streaming-latency claim (Apache 2.0)
• Qwen3-TTS model cards on Hugging Face — language list, cloning modes, checkpoint files (sizes measured from HF file listings, August 2026)
• GitHub API — star/fork counts and push dates, retrieved August 2026
• Simon Willison: "Qwen3-TTS" — January 22, 2026 independent test, download sizes, mlx-audio Mac path, and the "anyone with a GPU" quote
• hexgrad/Kokoro-82M model card — Kokoro parameters, license, and no-cloning training policy

---

FAQ {#faq}