Deploy ChatTTS 0.2.5: Chinese TTS Open Source Guide

Most broken ChatTTS setups start the same way: pip install ChatTTS on system Python, then surprise when Chinese numbers garble or torchaudio chokes on tensor rank. Isolation first. Pin 0.2.5 (as listed on PyPI/GitHub releases). Load once after normalizers exist.

ChatTTS from 2noise is a ~300M-parameter conversational TTS stack for LLM-style back-and-forth. Chinese and English. 24 kHz wavs. Prosody hooks for laughs, breaks, oral tone. Open weights on Hugging Face are the ~40k-hour base without SFT – not the claimed 100k+ closed train. Code: AGPLv3+. Weights: CC BY-NC 4.0, so research/non-commercial only (README license section).

System requirements for ChatTTS 0.2.5

Match iron to what the project and field guides actually publish (figures below as documented for current 0.2.x installs; re-check if your driver stack is newer).

CPU-only will run. Dialogue loops feel sticky. v0.2.5 release notes add partial DML – treat DML as experimental, not a promise.

Skipping this table is how people burn an evening on “install succeeded” and still OOM on a polite 40-second line. Hardware is boring. Broken first demos are worse.

Official download sources

• Code + tags: github.com/2noise/ChatTTS (v0.2.5)
• Wheel: PyPI chattts 0.2.5
• Weights: huggingface.co/2Noise/ChatTTS
• Site: chattts.com

PyPI is enough for normal installs. Git URL only when you truly need commits past the 0.2.5 tag. Random forks lag the chat.load() API.

Install ChatTTS 0.2.5 step by step

Fresh conda + pinned wheel. Global site-packages is how torch versions collide with whatever else you installed last month.

1. Env:

   conda create -n chattts python=3.11 -y
   conda activate chattts

2. CUDA-aware torch (example cu121 index – swap per pytorch.org if your driver needs another build):

   pip install torch torchaudio --index-url https://download.pytorch.org/whl/cu121

3. Package pin:

   pip install ChatTTS==0.2.5

4. Chinese normalizers. On Linux, requirements.txt platform markers often pull WeTextProcessing for you. If missing: pip install WeTextProcessing.

   Windows is the trap: pynini first from conda-forge, then the text stack.

   conda install -c conda-forge pynini=2.1.5 -y
   pip install WeTextProcessing

   Turns out without that pair, Chinese numbers and punctuation routinely sound chewed up – markers gate the heavy deps to Linux only in the raw requirements file.

5. Full repo only if you want WebUI/examples:

   git clone https://github.com/2noise/ChatTTS
   cd ChatTTS
   pip install --upgrade -r requirements.txt

Skip TransformerEngine and flash-attn unless you are hacking the model. README marks both unrecommended; flash-attn can slow generation.

Pro tip: Flaky network? huggingface-cli download 2Noise/ChatTTS before the first chat.load(). Otherwise that call sits on a multi-hundred-MB fetch into the HF cache.

First-time configuration

No YAML. Smallest working script:

import torch
import torchaudio
import ChatTTS

torch._dynamo.config.cache_size_limit = 64
torch._dynamo.config.suppress_errors = True

chat = ChatTTS.Chat()
chat.load(compile=False) # flip True later; first run stays simple

texts = ["你好,这是 ChatTTS 0.2.5 的中文测试。", "Hello from open-source Chinese TTS."]
wavs = chat.infer(texts)

for i, w in enumerate(wavs):
 wav = torch.from_numpy(w)
 try:
 torchaudio.save(f"out_{i}.wav", wav.unsqueeze(0), 24000)
 except Exception:
 torchaudio.save(f"out_{i}.wav", wav, 24000)

Same voice across lines – sample once, reuse:

spk = chat.sample_random_speaker()
params = ChatTTS.Chat.InferCodeParams(spk_emb=spk, temperature=0.3, top_P=0.7, top_K=20)
wavs = chat.infer(texts, params_infer_code=params)

Sentence style: refine prompts like [oral_2][laugh_0][break_4]. Word-level: [uv_break], [laugh], [lbreak].

Cloned tree? Gradio: python examples/web/webui.py. Batch CLI: python examples/cmd/run.py "句子一" "句子二".

Verify the install works

python -c "import ChatTTS; print(getattr(ChatTTS, '__version__', 'ok'))"
python -c "import torch; print('cuda:', torch.cuda.is_available())"

Run the script. Pass bar: no traceback, out_0.wav / out_1.wav at 24 kHz, both languages intelligible. First call is the slow one (download, maybe compile). Later GPU calls should lean toward the documented RTF ballpark.

Common install errors and fixes

Field reports, not lab fiction:

• CUDA OOM – One string at a time, shorter text, or more VRAM. Official FAQ-style guidance treats ~4 GB for ~30 s as a floor, not a comfort zone.
• Garbled Chinese / bad numbers – UTF-8 sources + WeTextProcessing; on Windows, pynini 2.1.5 via conda-forge first (see install step).
• torchaudio.save shape error – Official basic snippet uses try/except with unsqueeze(0) vs raw 1D. torchaudio builds disagree on rank.
• Static / harsh treble – On purpose. README disclaimer: open weights trained with added high-frequency noise and compression as an anti-abuse measure. compile=True after a clean cold start can sound less rough. It will not erase the watermark. Closed models still win on polish.
• Stuck first load – HF download. Pre-cache or set a mirror on restricted networks.
• Silent death, no traceback – Seen on Python 3.12 + some CUDA 12.x stacks during GPT generate paths (community issue threads). Drop to the documented 3.11 env.
• macOS ARM pip-only pain – Conda for scientific deps; pure pip pynini stacks stay fragile on arm64.
• load_models in old posts – Public 0.2.x API is chat.load(...). v0.2.5 also fixed a narrow() RuntimeError and tracked newer transformers – ignore 2024 copy-paste that never got updated.

Speaker drift on long takes? Autoregressive TTS does that even when the install is fine. Resample the embedding or generate a few candidates and pick one.

If the open checkpoint always sounds slightly “radio AM” next to a commercial voice, is that a failed setup – or the tradeoff you accepted for weights you can actually download? Worth deciding before you spend a week on EQ chains.

Upgrade and uninstall

pip install -U ChatTTS==0.2.5
# or commits past the tag:
pip install -U git+https://github.com/2noise/ChatTTS

Release notes for v0.2.5 call out partial DML, the narrow() fix, a requests dependency, and newer transformers tracking. Jumping from 0.1.x? Clear __pycache__ if imports look haunted. No migration DB.

pip uninstall ChatTTS -y
conda deactivate
conda env remove -n chattts -y
# optional: rm -rf ~/.cache/huggingface/hub/models--2Noise--ChatTTS

FAQ

Is ChatTTS free for commercial products?

No. CC BY-NC 4.0 on the weights. Public checkpoint is academic/research oriented unless you negotiate something else.

How do I keep the same voice across a long Chinese script?

You are narrating a 12-line product demo and line 7 suddenly sounds like a cousin. Fix: spk = chat.sample_random_speaker() once, keep that embedding string, pass InferCodeParams(spk_emb=spk, ...) on every infer. Restart the process? You still have the string – that is the reliable pattern.

Docker or one-click Windows builds?

Core repo is pip/conda. Community images and ChatTTS-ui style wrappers exist if you want a browser shell. They trail tags. Pin digests and still check behavior against 0.2.5. For an auditable research box, conda + ChatTTS==0.2.5 is simpler than chasing someone else’s layer cake.

Next: create chattts, install ChatTTS==0.2.5, run the two-language test, play the wavs. Only then flip compile=True for batch work – remember that first cold compile is the long one.