Sixty seconds of audio used to be the price of a cloned voice — and you paid it to a cloud API, per character, with your audio leaving your machine. IndexTTS 2.5 moves the whole job onto your own hardware: a 0.8-billion-parameter model from bilibili’s Index team that clones a voice from a single reference clip, speaks five languages, and lets you steer the emotion and the pace of what it says. The repo, index-tts/index-tts, has nearly 25,000 stars and was updated the day this guide was written, with 2.5 as the current release. It is the local, controllable end of the voice-cloning spectrum we mapped in our ElevenLabs vs PlayHT comparison — no account, no per-character bill, and the audio never leaves your disk.

This guide installs IndexTTS 2.5 the way its README prescribes, clones a voice in the WebUI and from a Python script, then pushes the two controls that make it more than a party trick: emotion and speed. Every command below comes from the project’s own README, verified against the repository on November 8, 2026.

What you’ll need

  • A machine with an NVIDIA GPU and CUDA Toolkit 12.8 or newer installed — the README’s install path assumes CUDA, and no CPU-only path is documented.
  • git and uv (Astral’s Python package manager, which the README requires for a reliable install).
  • About 30 minutes, plus download time for the model.
  • A short, clean recording of the voice you want to clone — one you have the right to use. The repo ships example voices for a first run, so you can start without recording anything.

Step 1 — Install IndexTTS 2.5

Clone the repository and let uv build the environment. The README is explicit: uv is required, and it creates the project virtual environment and pins the right Python and dependency versions for you.

git clone https://github.com/index-tts/index-tts.git && cd index-tts
pip install -U uv
uv sync --all-extras

The --all-extras flag pulls in every optional feature, including the WebUI (recommended) and DeepSpeed. On Windows, DeepSpeed can be hard to install — the README says to drop --all-extras and add the other feature flags manually instead. If you hit a CUDA error during install, check that CUDA Toolkit 12.8 or newer is actually installed. Then verify your GPU is detected:

uv run tools/gpu_check.py
A condenser microphone beside a laptop showing a simple audio waveform, in a warm home studio
The setup for this guide: a microphone, a laptop, and a reference clip. The model does the rest locally.

Step 2 — Download the IndexTTS-2.5 model

The weights live on Hugging Face as IndexTeam/IndexTTS-2.5 (a ModelScope mirror exists under the same name). Install the Hugging Face CLI through uv and download into a checkpoints directory:

uv tool install "huggingface-hub"
hf download IndexTeam/IndexTTS-2.5 --local-dir=checkpoints

The ModelScope alternative, if Hugging Face is slow from your network:

uv tool install modelscope-hub
modelscope download --model IndexTeam/IndexTTS-2.5 --local_dir checkpoints

If the hf or modelscope commands are not found after installing, read the uv tool output — it tells you how to add the tools to your PATH. A few small models are still downloaded automatically on first run; if Hugging Face is slow, set HF_ENDPOINT="https://hf-mirror.com" first, per the README.

Step 3 — Clone your first voice in the WebUI

One command starts the demo:

uv run webui.py

Open http://127.0.0.1:7860 in your browser. Pick a reference voice — the example clips in examples/ are downloaded on demand the first time the WebUI starts — type your text, choose the language, and generate. The WebUI exposes the half-precision switch: enable BF16 inference for IndexTTS-2.5 and you get faster generation at lower VRAM use, with very small quality loss, according to the README. Run uv run webui.py -h to see every option, including DeepSpeed acceleration and compiled CUDA kernels. The README is candid about DeepSpeed: it may speed things up on some systems and slow them down on others, so try both.

That first generation is the whole point of the tool. A voice you recorded this morning can now read anything you type, in English, Chinese, Japanese, Spanish, or Arabic — including a language the reference speaker never spoke.

Step 4 — Clone a voice from Python

The WebUI is for exploring; scripts are for building. The Python API takes the same three ingredients — a reference clip, text, and a language:

from indextts.infer_v2_5 import IndexTTS2

tts = IndexTTS2(cfg_path="checkpoints/config.yaml",
                model_dir="checkpoints", use_bf16=True)

tts.infer(spk_audio_prompt="examples/voice_01.wav",
          text="Translate for me, what a surprise!",
          lang="EN", output_path="gen.wav", verbose=True)

Run scripts with uv run so they execute inside the project environment, and add the current directory to PYTHONPATH if imports complain. There is also a command-line entry point that needs no script at all:

PYTHONPATH="$PYTHONPATH:." uv run indextts/infer_v2_5.py \
  --cfg_path checkpoints/config.yaml \
  --model_dir checkpoints \
  --text "Hello world" \
  --lang EN

The default prompt voice lives in examples/. If you never started the WebUI, fetch the examples first with uv run python -c "from indextts.utils.examples_downloader import ensure_examples_available; ensure_examples_available()". For production serving rather than one-off scripts, the project points to a vLLM recipe for IndexTTS.

Flowing ribbons of teal, amber, and violet light visualising a voice as sound waves
One reference clip, five languages: the same voice can read text it never spoke, in a language it never used.

Step 5 — Steer the emotion

This is where IndexTTS 2.5 separates itself from a plain voice clone. Three mechanisms, in increasing order of control:

An emotional reference clip. Pass a second audio file that carries the feeling you want, and dial its strength with emo_alpha (0.0 to 1.0, default 1.0):

tts.infer(spk_audio_prompt="examples/voice_07.wav",
          text="Welcome to the show. Tonight, everything changes.",
          lang="EN", output_path="gen.wav",
          emo_audio_prompt="examples/emo_sad.wav",
          emo_alpha=0.9, verbose=True)

An emotion vector. Skip the second clip and specify eight intensities directly, in the order happy, angry, sad, afraid, disgusted, melancholic, surprised, calm. This example leans hard into sadness:

tts.infer(spk_audio_prompt="examples/voice_09.wav",
          text="I am sorry. My memory really is terrible.",
          lang="EN", output_path="gen.wav",
          emo_vector=[0, 0, 0.8, 0, 0, 0, 0, 0],
          use_random=False, verbose=True)

Emotion from the text itself. Set use_emo_text=True and the model derives the emotion vector from your script; the README recommends an emo_alpha around 0.6 or lower for natural results. One gotcha, straight from the docs: for IndexTTS-2.5, use_emo_text=True requires constructing the model with use_qwen_emo=True, or it raises a RuntimeError. You can also pass an explicit emotion description with emo_text to control the feeling separately from the spoken words.

Step 6 — Control speed and pronunciation

Speaking speed is a single multiplier, duration_factor: above 1.0 slows speech down, below 1.0 speeds it up, valid from 0.5 to 2.0, default 1.0.

# Slow down (1.2x duration)
tts.infer(spk_audio_prompt="examples/voice_01.wav",
          text="Hello, and welcome to this demonstration.",
          lang="EN", output_path="gen_slow.wav",
          duration_factor=1.2, verbose=True)

# Speed up (0.8x duration)
tts.infer(spk_audio_prompt="examples/voice_01.wav",
          text="Hello, and welcome to this demonstration.",
          lang="EN", output_path="gen_fast.wav",
          duration_factor=0.8, verbose=True)

Pronunciation is pinned inline. IndexTTS 2.5 supports Pinyin, CMU phonemes, and Japanese Kana annotations, so a heteronym lands the way you mean it. The README’s English example disambiguates minute as a unit of time versus a tiny detail:

He had a <minute|M IH1 . N AH0 T> to examine the <minute|M AY0 . N UW1 T> details of the contract.

What you built

A local voice-cloning studio: one model, one reference clip, and a voice that reads any text in five languages, with its emotion, speed, and pronunciation under your control — no API key, no per-character bill, and no audio uploaded anywhere. The same three calls drive the WebUI for experiments and a script for batch work, and the vLLM recipe takes it into production serving.

When to use this vs alternatives

IndexTTS 2.5 is the pick when the voice itself matters and you want it local. Chatterbox is the closest local rival: MIT-licensed, 23 languages, and a 10-second clip is enough — but every file it generates carries a watermark, and it has no equivalent of IndexTTS’s emotion vector. Kokoro-82M runs on a plain CPU and is the better choice for straight narration, but it offers 54 preset voices and no cloning at all. And if you do not want to run hardware, the cloud services in our ElevenLabs vs PlayHT comparison still win on convenience — at the cost of per-character pricing and sending your audio to someone else’s servers.

Honest limitations

Four things to know before you commit. First, you need a CUDA GPU: the install guide assumes one, ships a GPU check script, and documents no CPU-only path, so a laptop without NVIDIA hardware is a non-starter. Second, the license: IndexTTS is released under the bilibili Model Use License Agreement, not an open-source license — read LICENSE and DISCLAIMER, and route commercial use through [email protected]. Third, the numbers are honest about where it is strongest: on the project’s own CV3-Eval zero-shot benchmark, IndexTTS 2.5 averages 6.75% word error rate and 73.18 speaker similarity, with Chinese (4.36 / 77.10) ahead of English (5.12 / 68.06) — and the RL variant improves both (6.00 / 73.63). Fourth, the clone is only as good as the clip: a noisy, echoey, or multi-speaker reference will come back as a noisy, echoey, multi-speaker voice. And the obvious ethical line: clone voices you have the right to use, and say so when you publish the result.

Frequently asked questions

Do I need a GPU to run IndexTTS 2.5?

Yes. The install guide assumes a CUDA GPU — NVIDIA’s CUDA Toolkit 12.8 or newer — and ships a gpu_check.py script to verify your card is detected. BF16 inference halves VRAM use. No CPU-only path is documented in the README.

How long a voice sample does IndexTTS 2.5 need to clone a voice?

The README says a single reference audio clip, with no fixed duration stated. Use a short, clean recording of the voice you have the right to use; the repo ships example voices in examples/ (populated the first time the WebUI starts) for a first run.

Can I use IndexTTS 2.5 in a commercial product?

It is released under the bilibili Model Use License Agreement, not an open-source license — read the LICENSE and DISCLAIMER files before any commercial use. For commercial usage and cooperation, the project lists [email protected].

Related coverage

Sources