Install XTTS v2 with Coqui-TTS Fork: A 2026 Guide

The most common question I see on r/LocalLLaMA and the Coqui discussions: “I followed a tutorial, ran pip install TTS, and it crashes the moment I try to load XTTS v2. What am I doing wrong?”

Short answer: the tutorial is from 2023. The world moved. This guide walks through installing XTTS v2 via the maintained Coqui-TTS fork in 2026 – including the one PyTorch change that quietly killed every old install script.

Why the old install commands stopped working

Coqui AI (the company) shut down in January 2024, so the original coqui-ai/TTS repo is no longer actively developed. The last release on that repo – v0.22.0, dated December 12, 2023 – is what you get when you run pip install TTS today. Two and a half years is a geological era in ML tooling.

Then PyTorch made a security-motivated change. What the security patch actually does: torch.load() used to deserialize entire Python objects from checkpoint files, including arbitrary class instances. From PyTorch 2.6 onward, the weights_only parameter defaults to True, meaning only raw tensors load – Python class objects are blocked. XTTS stores its config as an XttsConfig class instance inside the checkpoint, so the loader refuses. The result is a WeightsUnpickler error that every guide published before 2025 never anticipated.

The fix isn’t a workaround. There’s an actively-maintained community fork at idiap/coqui-ai-TTS, published on PyPI as coqui-tts, which patches the PyTorch 2.6 compatibility issue at the source. That’s what we’ll install.

System requirements (real numbers, 2026)

Per the idiap fork’s README and what actually holds up in practice:

The model weights are about 2 GB, downloaded automatically on first startup (per the SillyTavern XTTS docs, as of early 2025). The rest of disk usage is PyTorch, CUDA wheels, and dependency cache.

Install XTTS v2 step by step

One non-obvious thing first: from coqui-tts 0.27.4, PyTorch is not bundled and must be installed manually before the TTS library. The idiap fork README is explicit about this. Older guides promising a single-line install predate that version – follow them and you’ll get a broken environment silently.

1. Create an isolated environment

# Python 3.11 works well - 3.10 also fine
python3.11 -m venv xtts-env
source xtts-env/bin/activate # Linux/macOS
# xtts-envScriptsactivate # Windows PowerShell

2. Install PyTorch matching your hardware

Pick the right wheel from the official PyTorch install page. For CUDA 12.1:

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

CPU-only is one command shorter (pip install torch torchaudio) but expect roughly 10-20× slower inference. Mac users on Apple Silicon: install the default wheel – MPS backend has caveats noted later.

3. Install the maintained fork

pip install coqui-tts

Not pip install TTS. Not pip install coqui-ai-tts. The package is coqui-tts. The import path stays from TTS.api import TTS – that’s why most community scripts drop in without changes.

First-time setup and the license gate

Type y when you see it – but read first. On first model load the library prompts you to accept the Coqui Public Model License (CPML). The weights are non-commercial only; if you’re shipping a paid product, XTTS v2 is not the right model. Alternatives with permissive licenses include Piper and Kokoro.

Create xtts_test.py:

import torch
from TTS.api import TTS

device = "cuda" if torch.cuda.is_available() else "cpu"
print(f"Using device: {device}")

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

tts.tts_to_file(
 text="If you can hear this, the install worked.",
 speaker_wav="reference.wav", # 6+ second mono WAV
 language="en",
 file_path="output.wav",
)

You need a reference.wav – any clean voice recording at least 6 seconds long. According to the XTTS-v2 model card, 15-30 seconds gives noticeably better timbre than the bare minimum. The first run pulls ~2 GB into ~/.local/share/tts/ on Linux or %LOCALAPPDATA%tts on Windows.

On reference audio quality: Background noise gets faithfully cloned. A phone voice memo recorded in a kitchen will produce a clone with all that ambience baked in. Record into a USB mic in a quiet room, or pull a clean clip from a podcast intro. The model can’t distinguish “voice character” from “room character” – it copies both.

Verify the install actually works

Two checks. First, confirm the package version:

python -c "import TTS; print(TTS.__version__)"

You should see something in the 0.27.x or 0.28.x range as of mid-2026. Anything starting with 0.22 means pip grabbed the dead original package – uninstall and retry with the correct name.

Second, confirm the binary entry point is on PATH:

tts --list_models | grep xtts

If the script ran and output.wav plays a recognizable clone of your reference voice, you’re done.

Common errors and how to fix them

These two failures account for the vast majority of issue reports on GitHub and the Hugging Face discussions board.

Error: WeightsUnpickler error: Unsupported global XttsConfig

The signature 2026 failure. Full message: WeightsUnpickler error: Unsupported global: GLOBAL TTS.tts.configs.xtts_config.XttsConfig was not an allowed global by default.

You hit this when the original TTS package meets PyTorch 2.6+. Three fixes, in order of preference:

1. Switch to the fork – pip uninstall TTS, then pip install coqui-tts. The idiap maintainers patched this at the source (per the fork README, as of the 0.27.x line).
2. Set an env var if you can’t switch right now: export TORCH_FORCE_NO_WEIGHTS_ONLY_LOAD=1 before running. Works, but note this re-enables the security behavior PyTorch was trying to remove – a short-term fix, not a permanent home.
3. Pin PyTorch to a pre-2.6 release: pip install torch==2.5.1 torchaudio. The community workaround documented in HF discussions #113. You’re trading away future security patches, so treat this as temporary.

Error: MPS device crashes on Apple Silicon

XTTS uses operations that aren’t fully covered by Apple’s Metal Performance Shaders backend across all PyTorch versions. If you see MPS-related crashes or assertion errors, force CPU: pass .to("cpu") instead of letting the script auto-detect MPS. Slower, but it completes. This is a known open issue in the community – check the idiap fork’s GitHub issues for the latest status before filing a duplicate.

The Docker alternative (one line, no Python pain)

If the Python environment fights you, the idiap fork ships a CPU container:

docker run --rm -it -p 5002:5002 
 ghcr.io/idiap/coqui-tts-cpu 
 python3 TTS/server/server.py 
 --model_name tts_models/multilingual/multi-dataset/xtts_v2

Open http://localhost:5002 for the demo UI. The Docker image and server port are documented in the fork’s README.

Upgrading and clean uninstall

Upgrading is straightforward:

pip install --upgrade coqui-tts

Your downloaded XTTS v2 weights stay compatible across library versions. If you’re migrating from the original TTS package, uninstall it first (pip uninstall TTS) – both register the same TTS module name, so they’ll conflict if both are present.

Full removal:

pip uninstall coqui-tts
# Remove cached model weights (~2 GB)
rm -rf ~/.local/share/tts/ # Linux
rm -rf ~/Library/Application Support/tts/ # macOS
# Windows: delete %LOCALAPPDATA%tts

No daemons, no registry keys. Clean exit.

FAQ

Is XTTS v3 coming?

Nothing public. The idiap fork is a maintenance effort – the maintainers keep compatibility with new Python and PyTorch versions, but developing a new generation of the model would require access to Coqui’s original training infrastructure and datasets, which aren’t public. v2 is what you get, and as of mid-2026 it remains competitive for offline multilingual cloning.

Can I use XTTS v2 commercially?

No. The Coqui Public Model License (CPML) covers non-commercial use only. Full stop. Personal projects, research, internal demos: fine. Shipping it in a paid product: not covered. Switch to Piper or Kokoro for commercial work – both carry permissive licenses.

Why does my cloned voice have the wrong accent?

XTTS clones timbre well from a short clip, but accent is partly steered by the language parameter, not just the reference audio. Pass language="en" with a French-accented speaker and you’ll get a softened, more neutral English output – the model normalizes toward the target language’s phonetic norms. For cross-lingual cloning that preserves the source accent, pass the speaker’s native language code instead. If you need tighter accent reproduction within a single language, fine-tuning the GPT encoder on a larger reference set helps; the XTTS model card includes a recipe for that.

Next step: record a 20-second clip in a quiet room and run the verification script. If output.wav sounds like you, move on to batch synthesis – the same tts.tts_to_file() call inside a loop handles narrating an entire chapter without any extra setup.