🐸 Coqui TTS User Guide

Coqui TTS (package name TTS) is a Python library for advanced Text-to-Speech generation. It bundles dozens of pretrained neural voices in 1100+ languages, a one-line command-line tool, a Python API, a local web server, and full training recipes — so you can turn text into natural-sounding speech, clone a voice from a few seconds of reference audio, or convert one speaker's voice into another.

This guide covers everything you need to use the released models: installing the package, choosing a voice, synthesizing speech from the command line and from Python, voice cloning, voice conversion, and running the local demo server. Training your own models, architecture internals, and security hardening live in the companion Admin Guide.

Note

Coqui TTS is documented here at version 0.22.0 (commit dbf1a08). The original company behind Coqui has since shut down, so the project is effectively frozen at this release and community-maintained. The voices and code below work, but expect compatibility friction with very new versions of PyTorch and transformers — see Troubleshooting.

1. Quick Start

Install the package, then make your computer talk in two lines.

Important

Coqui TTS requires Python ≥ 3.9 and < 3.12. Installation fails on Python 3.12+ with a RuntimeError. Use a 3.9–3.11 virtual environment.

Command line

pip install TTS
tts --text "Hello world, spoken by Coqui." --out_path hello.wav

 > tts_models/en/ljspeech/tacotron2-DDC is downloaded.
 > Text: Hello world, spoken by Coqui.
 > Saving output to hello.wav

Python

from TTS.api import TTS

tts = TTS("tts_models/en/ljspeech/tacotron2-DDC")
tts.tts_to_file(text="Hello world, spoken by Coqui.", file_path="hello.wav")

The first run downloads the default English model (tts_models/en/ljspeech/tacotron2-DDC) and writes a .wav file you can play in any audio player.

Tip

No model specified means Coqui uses its default LJSpeech English voice. To pick a different voice, see Choosing a Voice.

To clone a voice instead, point the high-quality XTTS v2 model at a reference clip:

from TTS.api import TTS

tts = TTS("tts_models/multilingual/multi-dataset/xtts_v2")
tts.tts_to_file(
    text="This sentence is spoken in a cloned voice.",
    speaker_wav="reference.wav",   # a few seconds of the voice to clone
    language="en",
    file_path="cloned.wav",
)

2. What You Can Do

Note

Coqui ships several model families with different strengths: end-to-end models (XTTS, VITS, YourTTS, Bark, Tortoise) and classic two-stage spectrogram models (Tacotron2, Glow-TTS, FastPitch, Speedy-Speech, Overflow) that pair with a separate vocoder. XTTS v2 is the most capable all-rounder for cloning and multilingual work.

3. Installation

3.1 From PyPI (recommended for synthesis only)

If you only want to generate speech with the released models, install from PyPI:

pip install TTS

3.2 From source (for training or development)

git clone https://github.com/coqui-ai/TTS
cd TTS
pip install -e .[all,dev,notebooks]   # select the extras you need

Available extras: all, dev, notebooks, ja (Japanese support).

3.3 On Ubuntu / Debian

A Makefile provides convenience targets:

make system-deps   # installs OS-level audio/build dependencies (Ubuntu/Debian only)
make install       # installs TTS in editable mode

3.4 With Docker (no install)

Coqui publishes prebuilt images so you can run TTS without installing anything locally:

docker run --rm -it -p 5002:5002 --entrypoint /bin/bash ghcr.io/coqui-ai/tts-cpu
python3 TTS/server/server.py --list_models                       # see available models
python3 TTS/server/server.py --model_name tts_models/en/vctk/vits  # start the server

Then open http://[::1]:5002/ in a browser. GPU image variants are also published.

Warning

The hard Python version gate lives in setup.py: installing on Python 3.12 or newer raises RuntimeError: TTS requires python >= 3.9 and < 3.12. Create your environment with a supported interpreter before installing — for example python3.11 -m venv .venv.

3.5 Verify the install

tts --list_models

 Name format: type/language/dataset/model
 1: tts_models/multilingual/multi-dataset/xtts_v2
 2: tts_models/multilingual/multi-dataset/xtts_v1.1
 ...

If tts --list_models prints a numbered model list, you're ready.

4. Choosing a Voice (the Model Zoo)

Every Coqui voice has a four-part name:

<model_type>/<language>/<dataset>/<model_name>

For example tts_models/en/ljspeech/tacotron2-DDC is a TTS model, English, trained on the LJSpeech dataset, using the Tacotron2-DDC architecture. The three model types are:

4.1 Browse and inspect models

# List every available model
tts --list_models

# Show details for a model by its full name
tts --model_info_by_name tts_models/en/ljspeech/tacotron2-DDC

# Show details for a model by its index in --list_models
tts --model_info_by_idx tts_models/3

4.2 Headline models

Important

XTTS v2 is not open source. It ships under the Coqui Public Model License (CPML), which restricts commercial use, and it is gated: the first time you load it you must accept the terms. To pre-accept non-interactively (for scripts/servers), set the environment variable COQUI_TOS_AGREED=1. Other voices carry their own licenses (Apache-2.0, MPL, CC-BY-SA, MIT, etc.) — check --model_info_by_name before any commercial use.

Tip

Fairseq / MMS voices unlock 1100+ languages with one naming convention: tts_models/<lang-iso_code>/fairseq/vits. Look up ISO codes in Meta's MMS language table. These are single-speaker but cover the long tail of languages no dedicated Coqui voice exists for.

4.3 Where models are stored

Downloaded models are cached on disk so they download only once. The cache location is resolved in this order:

1. $TTS_HOME/tts/ if TTS_HOME is set
2. $XDG_DATA_HOME/tts/ if XDG_DATA_HOME is set
3. otherwise ~/.local/share/tts/

See the Reference for these environment variables.

5. Synthesizing Speech from the Command Line

The tts command is installed as a console script. Its single most-used form is:

tts --text "Text to speak" --out_path speech.wav

5.1 Common recipes

# Default English voice
tts --text "Text for TTS" --out_path output/speech.wav

# Pick a specific model
tts --text "Text for TTS" \
    --model_name "tts_models/en/ljspeech/glow-tts" \
    --out_path output/speech.wav

# Pick a model AND a specific vocoder
tts --text "Text for TTS" \
    --model_name "tts_models/en/ljspeech/glow-tts" \
    --vocoder_name "vocoder_models/en/ljspeech/univnet" \
    --out_path output/speech.wav

# Run your own trained model (uses Griffin-Lim if no vocoder given)
tts --text "Text for TTS" \
    --model_path path/to/model.pth \
    --config_path path/to/config.json \
    --out_path output/speech.wav

# Pipe the wav straight to an audio player instead of a file
tts --text "Text for TTS" --pipe_out --out_path output/speech.wav | aplay

 > Text: Text for TTS
 > Saving output to output/speech.wav

5.2 Multi-speaker models

Models like tts_models/en/vctk/vits contain many voices. List them, then pick one:

# 1. See the available speaker IDs
tts --model_name "tts_models/en/vctk/vits" --list_speaker_idxs

# 2. Synthesize with a chosen speaker
tts --text "Text for TTS." \
    --model_name "tts_models/en/vctk/vits" \
    --speaker_idx p225 \
    --out_path output/speech.wav

 > Available speaker ids: (Set --speaker_idx flag to one of these values to use the multi-speaker model.
 {'p225': 0, 'p226': 1, 'p227': 2, ...}

5.3 Multilingual models

For XTTS and other multilingual models, list and select a language ID:

tts --model_name "tts_models/multilingual/multi-dataset/xtts_v2" --list_language_idxs
tts --text "Bonjour le monde." \
    --model_name "tts_models/multilingual/multi-dataset/xtts_v2" \
    --language_idx fr \
    --speaker_wav reference.wav \
    --out_path output/fr.wav

5.4 Voice cloning from the command line

Pass one or more reference clips with --speaker_wav (multiple files are averaged):

tts --text "This is a cloned voice." \
    --model_name "tts_models/multilingual/multi-dataset/xtts_v2" \
    --language_idx en \
    --speaker_wav my_voice_1.wav my_voice_2.wav \
    --out_path cloned.wav

5.5 Voice conversion from the command line

Convert the voice in --source_wav into the voice from --target_wav:

tts --model_name "voice_conversion_models/multilingual/vctk/freevc24" \
    --source_wav my_voice.wav \
    --target_wav target_voice.wav \
    --out_path converted.wav

5.6 Full CLI flag reference

Note

Running tts with none of --text, --list_models, --list_speaker_idxs, --list_language_idxs, --reference_wav, --model_info_by_idx, --model_info_by_name, --source_wav, or --target_wav set simply prints the help screen.

6. Synthesizing Speech from Python

The TTS class in TTS.api is the programmatic entry point. Construct it with a model name (or your own paths), then call tts() (returns waveform samples) or tts_to_file() (writes a .wav).

6.1 Single-speaker model

import torch
from TTS.api import TTS

device = "cuda" if torch.cuda.is_available() else "cpu"

tts = TTS("tts_models/de/thorsten/tacotron2-DDC").to(device)
tts.tts_to_file(text="Ich bin eine Testnachricht.", file_path="de.wav")

Tip

Use tts.to("cuda") to move the model to the GPU. The older gpu=True constructor argument still works but is deprecated — prefer .to(device).

6.2 Multi-speaker, multilingual model (XTTS)

from TTS.api import TTS

tts = TTS("tts_models/multilingual/multi-dataset/xtts_v2").to("cuda")

# Voice cloning requires a reference clip + a language for XTTS
wav = tts.tts(text="Hello world!", speaker_wav="reference.wav", language="en")
tts.tts_to_file(text="Hello world!", speaker_wav="reference.wav", language="en", file_path="out.wav")

Note

Coqui validates your arguments against the model. If a model is multi-speaker you must pass speaker or speaker_wav; if it is multilingual you must pass language. Passing speaker/language to a model that doesn't support them also raises a ValueError. See Troubleshooting.

6.3 Inspect the loaded model

tts.is_multi_speaker     # True/False
tts.is_multi_lingual     # True/False
tts.speakers             # list of speaker names, or None
tts.languages            # list of language codes, or None
print(TTS().list_models())  # browse the zoo

6.4 Fairseq / MMS voices (1100+ languages)

from TTS.api import TTS

api = TTS("tts_models/deu/fairseq/vits")
api.tts_to_file("Wie geht es dir?", file_path="de_fairseq.wav")

6.5 The tts() and tts_to_file() parameters

Tip

Leave split_sentences=True (the default) for long passages — it keeps each chunk within a model's text-length and VRAM limits. Set it to False only for short single sentences where you want to avoid the small concatenation seams; it uses more VRAM.

Caution

The emotion and speed parameters exist on tts()/tts_to_file() but only ever worked with the discontinued Coqui Studio cloud models. Passing both together raises ValueError: Emotion and speed can only be used with Coqui Studio models. Which is discontinued. Leave them unset with local models.

7. Voice Cloning

Voice cloning recreates a target voice from a short reference clip. Use a cloning-capable model (XTTS v2, YourTTS, Bark) and pass the reference with speaker_wav.

from TTS.api import TTS

tts = TTS("tts_models/multilingual/multi-dataset/your_tts").to("cuda")

tts.tts_to_file("This is voice cloning.",
                speaker_wav="my/cloning/audio.wav", language="en", file_path="en.wav")
tts.tts_to_file("C'est le clonage de la voix.",
                speaker_wav="my/cloning/audio.wav", language="fr-fr", file_path="fr.wav")
tts.tts_to_file("Isso é clonagem de voz.",
                speaker_wav="my/cloning/audio.wav", language="pt-br", file_path="pt.wav")

Tip

Use a clean, mono reference clip of a few seconds with minimal background noise. You can pass multiple clips (speaker_wav=["a.wav","b.wav"]); their speaker embeddings are averaged for a steadier voice. Coqui does not enforce a fixed clip length in code, but very short or noisy references degrade quality.

7.1 Clone any voice with two-stage conversion

Even models that can't clone directly can be combined with a voice-conversion model using tts_with_vc_to_file(). Coqui synthesizes the text in the base voice, then converts it to your reference speaker:

from TTS.api import TTS

tts = TTS("tts_models/de/thorsten/tacotron2-DDC")
tts.tts_with_vc_to_file(
    "Wie sage ich auf Italienisch, dass ich dich liebe?",
    speaker_wav="target/speaker.wav",
    file_path="output.wav",
)

8. Voice Conversion

Voice conversion recasts the speaker identity of an existing recording without changing the words. Coqui ships FreeVC for this.

from TTS.api import TTS

tts = TTS("voice_conversion_models/multilingual/vctk/freevc24").to("cuda")
tts.voice_conversion_to_file(
    source_wav="my/source.wav",     # the words / performance to keep
    target_wav="my/target.wav",     # the voice to adopt
    file_path="output.wav",
)

Note

source_wav supplies the content and timing; target_wav supplies the voice. The output says what source_wav said, in the voice of target_wav.

9. The Local Demo Server

Coqui includes a Flask web server with a browser UI and an HTTP API, installed as the tts-server console script.

9.1 Start the server

# Start with a chosen model on the default port 5002
tts-server --model_name tts_models/en/vctk/vits

# Or list models first
tts-server --list_models

Open http://localhost:5002/ for the web UI, or call the HTTP API directly.

9.2 HTTP API

# Synthesize via the HTTP API
curl "http://localhost:5002/api/tts?text=Hello%20from%20the%20server" --output speech.wav

For multi-speaker or multilingual models, add speaker_id, language_id, or style_wav query parameters.

9.3 Server flags

Caution

The demo server is built for local experimentation only. It binds to all network interfaces, has no authentication, and the MaryTTS-compatibility layer is minimal. Do not expose tts-server directly to the public internet — put it behind your own authenticated proxy if you need remote access. See the Admin Guide's security section.

10. Running on a GPU

Coqui uses PyTorch, so it runs on CPU by default and on NVIDIA GPUs when available.

Python

import torch
from TTS.api import TTS

device = "cuda" if torch.cuda.is_available() else "cpu"
tts = TTS("tts_models/multilingual/multi-dataset/xtts_v2").to(device)

Command line

tts --text "On the GPU" --model_name tts_models/en/ljspeech/vits --device cuda --out_path out.wav
# or the legacy flag:
tts --text "On the GPU" --use_cuda true --out_path out.wav

Tip

Large models like XTTS v2, Bark, and Tortoise are slow on CPU. Use a GPU for interactive work. Lightweight VITS and Tacotron2 models are usable on CPU for short text.

11. Troubleshooting

Error: RuntimeError: TTS requires python >= 3.9 and < 3.12 ...

Cause: You're installing on Python 3.12 or newer (or older than 3.9). The version is gated in setup.py. Solution: Create a 3.9–3.11 environment: python3.11 -m venv .venv && source .venv/bin/activate, then pip install TTS. Prevention: Check python --version before installing.

Error: ImportError: cannot import name 'isin_mps_friendly' from 'transformers.pytorch_utils'

Cause: Your installed transformers version is incompatible. Coqui pins transformers>=4.33.0 and breaks against transformers 5.x. Solution: Pin a compatible version, e.g. pip install "transformers>=4.33,<5". Prevention: Install Coqui in a clean environment so its pinned dependencies resolve correctly.

Error: AttributeError: 'GenerationConfig' object has no attribute 'do_stream'

Cause: XTTS streaming code is incompatible with transformers 5.0.0. Solution: Downgrade transformers below 5.0 (see above). Prevention: Avoid upgrading transformers past the 4.x line while using this release of Coqui.

Error: ModuleNotFoundError: No module named 'pkg_resources'

Cause: setuptools is missing or too new (it removed the legacy pkg_resources module) in your environment. Solution: pip install setuptools<81 (or install a setuptools version that still provides pkg_resources). Prevention: Use the dependency set Coqui installs rather than a bare interpreter.

Error: Exception: [!] You must agree to the terms of service to use this model.

Cause: You loaded a gated model (e.g. XTTS v2, license CPML) without accepting its terms. Solution: Accept interactively when prompted, or set COQUI_TOS_AGREED=1 in the environment for non-interactive scripts and servers. Prevention: Set COQUI_TOS_AGREED=1 in your service environment for gated models.

Error: ValueError: Model is multi-speaker but no 'speaker' is provided.

Cause: The model has multiple voices and you didn't choose one. Solution: Pass speaker="<id>" (or speaker_wav=... for cloning). List options with tts.speakers or tts --list_speaker_idxs. Prevention: Check tts.is_multi_speaker before synthesizing.

Error: ValueError: Model is multi-lingual but no 'language' is provided.

Cause: A multilingual model (XTTS) needs a target language. Solution: Pass language="en" (or --language_idx en). List options with tts.languages / --list_language_idxs. Prevention: Check tts.is_multi_lingual.

Error: ValueError: Model is not multi-speaker but 'speaker' is provided.

Cause: You passed speaker/language to a single-voice model that doesn't accept it. Solution: Remove the speaker/language argument for single-speaker, single-language models.

Error: RuntimeError: The hash of {file} does not match. Delete the file manually and retry.

Cause: A model download was corrupted or interrupted; its checksum doesn't match. Solution: Delete the cached file at the path shown and re-run to re-download. Prevention: Ensure a stable connection during the first download of large models.

Error: NotImplementedError: [!] only supports tar.gz, tgz, and zip archives.

Cause: A custom model URL points to an unsupported archive format. Solution: Repackage the model as .zip, .tar.gz, or .tgz.

Error: NotImplementedError: XTTS has a dedicated trainer ...

Cause: You tried to train/fine-tune XTTS through the generic training path. Solution: Use the dedicated XTTS fine-tuning recipe (see the XTTS docs and recipes/ljspeech).

Issue: A voice's first word is sometimes skipped

Cause: A known artifact in some attention-based models (community issue #4016). Solution: Prepend a short pause or punctuation, or try a different model (VITS/XTTS) for the same text.

Issue: coqui.ai links don't work / look wrong

Cause: The original Coqui company shut down and the coqui.ai domain is no longer controlled by the project (community issues #4418, #4392). Solution: Rely on the GitHub repository, the cached models, and this guide. Treat any content now served from coqui.ai with caution.

Tip

When something goes wrong, tts/bin/collect_env_info.py (run as python -m TTS.bin.collect_env_info) prints your environment details — useful when comparing against a known-good setup.

12. FAQ

Q: Do I need a GPU? No. Coqui runs on CPU. Lightweight models (VITS, Tacotron2) are fine on CPU for short text; large models (XTTS, Bark, Tortoise) are much faster on a GPU.

Q: Which model should I use for the best quality and voice cloning? tts_models/multilingual/multi-dataset/xtts_v2. It covers 17 languages and clones from a reference clip. Note its non-commercial CPML license.

Q: Can I use Coqui voices commercially? It depends on the specific model's license. XTTS v2 is CPML (non-commercial). Others range from Apache-2.0 and MIT to CC-BY-NC. Always run tts --model_info_by_name <name> and check the license field before commercial use.

Q: How many languages are supported? The dedicated Coqui voices cover ~20 languages; via Meta's Fairseq/MMS voices (tts_models/<iso>/fairseq/vits) you reach 1100+ languages.

Q: How do I clone a voice? Load a cloning-capable model (XTTS v2, YourTTS, Bark) and pass speaker_wav="reference.wav". For models that can't clone directly, use tts_with_vc_to_file().

Q: Where are downloaded models stored? Under $TTS_HOME/tts/, else $XDG_DATA_HOME/tts/, else ~/.local/share/tts/. Delete a model's folder there to force a re-download.

Q: How do I avoid the license prompt on a server? Set COQUI_TOS_AGREED=1 in the environment before loading a gated model.

Q: Can I run a long document through it? Yes — keep split_sentences=True (default). Coqui splits the text into sentences, synthesizes each, and concatenates them.

Q: Is the company still around? No. Coqui shut down, so this codebase is frozen at v0.22.0 and community-maintained. The models and code work, but new PyTorch/transformers releases may need version pinning.

Q: What's the difference between a "tts_model" and a "vocoder_model"? Two-stage TTS models produce a spectrogram that a separate vocoder turns into audio. End-to-end models (VITS, XTTS) do both in one model and need no separate vocoder. Coqui auto-selects each model's default vocoder for you.

Q: How do I serve TTS over HTTP? Run tts-server --model_name <name> and call GET/POST /api/tts. Keep it behind your own auth — it has none built in.

13. Reference

13.1 Model name format

<model_type>/<language>/<dataset>/<model_name>
# examples:
tts_models/en/ljspeech/tacotron2-DDC
tts_models/multilingual/multi-dataset/xtts_v2
vocoder_models/en/ljspeech/hifigan_v2
voice_conversion_models/multilingual/vctk/freevc24
tts_models/deu/fairseq/vits

13.2 Environment variables

13.3 Console scripts

13.4 Python API surface (from TTS.api import TTS)

13.5 Key dependencies

PyTorch (torch>=2.1) and torchaudio for the models; librosa, soundfile, scipy, numpy for audio; transformers>=4.33.0 for XTTS/Tortoise; gruut, pysbd, jieba/pypinyin (Chinese), jamo/g2pkk (Korean), bangla/bnnumerizer (Bangla) for text processing; flask for the demo server; trainer and coqpit for training/config. See the Admin Guide for the complete breakdown.