Fix BeamSearchScorer ImportError in Coqui TTS xtts_v2

The ImportError happens because Coqui TTS’s xtts_v2 code imports BeamSearchScorer from the transformers top-level API, and newer/unstable Transformers releases changed top-level exports. The fastest reliable fix is to install a transformers version known to match your TTS release (example: transformers==4.46.2 with TTS==0.25.3), or add a tiny runtime shim/try-except that imports BeamSearchScorer from transformers.generation.beam_search before importing TTS. Below you’ll find exact pip commands, a non-invasive shim you can paste into your script, and a small source patch if you prefer editing the package.

Contents

• Symptom & quick checks
• Root cause: transformers API / top-level exports changed (xtts_v2)
• Quick fixes — recommended package versions and pip commands
• Runtime shim and minimal source patch (copy-paste)
• Minimal reproducible environment (Python + package versions)
• Validation & how to test the fix
• Sources
• Conclusion

Symptom & quick checks

Your traceback shows the failure at the top-level import inside Coqui’s stream_generator module:

• The error line is in TTS/tts/layers/xtts/stream_generator.py where the code does from transformers import BeamSearchScorer, and Python raises ImportError: cannot import name ‘BeamSearchScorer’ from ‘transformers’.

You can confirm locally which versions are installed and whether the import works with these two quick checks:

• Check package versions:

• pip show TTS

• pip show transformers

• pip show torch

• Quick Python import test (run in your venv):

python - <<'PY'
import transformers
print("transformers:", transformers.__version__)
try:
 from transformers import BeamSearchScorer
 print("BeamSearchScorer: top-level import OK")
except Exception as e:
 print("BeamSearchScorer top-level import failed:", e)
 try:
 from transformers.generation.beam_search import BeamSearchScorer
 print("BeamSearchScorer: import from submodule OK")
 except Exception as e2:
 print("Submodule import failed:", e2)
PY

If the top-level import fails but the submodule import works, a runtime shim or a small patch will restore compatibility.

Root cause: transformers API / top-level exports changed (xtts_v2)

What’s happening? Coqui TTS (xtts_v2 code) imports BeamSearchScorer directly from transformers’ top-level exports; see the source where the import is performed in stream_generator.py. The repository file shows that TTS expects that symbol to be exported at top-level: https://raw.githubusercontent.com/coqui-ai/TTS/main/TTS/tts/layers/xtts/stream_generator.py.

Hugging Face transformers has had API reshuffles and some top-level exports were moved or restricted in newer/dev releases (see the transformers issue reporting import regressions in dev/5.0: https://github.com/huggingface/transformers/issues/42352). Coqui/TTS has also seen compatibility issues with changed transformers exports (see similar import failures reported in TTS issues like https://github.com/coqui-ai/TTS/issues/4165). Some released TTS versions were pinned to a narrow transformers range; for example, a community thread shows a released TTS pinned to transformers <=4.46.2 and >=4.43.0: https://github.com/idiap/coqui-ai-TTS/issues/306.

In short: a mismatch between the installed transformers release and the TTS code’s expected API (top-level exports) causes the ImportError.

Quick fixes — recommended package versions and pip commands

There are three practical paths. Pick one that fits your constraints.

A) Downgrade transformers to a compatible release (fastest, least invasive)

• Many released Coqui TTS builds are known to work with transformers in the 4.43–4.46 range. A commonly used combination is:
• TTS==0.25.3 and transformers==4.46.2 (example shown in community threads).
• Example (create a fresh venv and install pinned versions):

python3.11 -m venv venv
source venv/bin/activate
python -m pip install --upgrade pip
pip install "TTS==0.25.3" "transformers==4.46.2" "torch==2.2.2" "torchaudio==2.2.2" soundfile librosa

• Notes: Coqui’s repo lists transformers>=4.33.0 in requirements but packaged releases may be pinned tighter; see the repo requirements: https://raw.githubusercontent.com/coqui-ai/TTS/main/requirements.txt. Also TTS requires Python >=3.9 and <3.12 (so your Python 3.11 is supported): https://raw.githubusercontent.com/coqui-ai/TTS/main/setup.py.

B) Add a tiny runtime shim in your script (non-invasive, keeps current transformers)

• Put this at the very top of your test script (before any TTS import). It tries the top-level import, and if that fails it grabs the class from the submodule and attaches it to the transformers module so TTS’s top-level import succeeds:

# shim.py — place at top of your script (before "from TTS.api import TTS")
try:
 from transformers import BeamSearchScorer # preferred top-level
except Exception:
 try:
 from transformers.generation.beam_search import BeamSearchScorer
 except Exception:
 BeamSearchScorer = None
 if BeamSearchScorer is not None:
 import transformers as _transformers
 setattr(_transformers, "BeamSearchScorer", BeamSearchScorer)

# now it's safe to import TTS
from TTS.api import TTS

• This is quick and reversible. Use it when you want to keep a newer transformers installation.

C) Patch the installed Coqui TTS source (local edit)

• Edit the file that raises the error (path shown in your traceback — e.g., venv/lib/python3.11/site-packages/TTS/tts/layers/xtts/stream_generator.py). Replace the grouped top-level import of BeamSearchScorer with a try/except that falls back to the submodule:

# near the top of stream_generator.py
# original: from transformers import (BeamSearchScorer, ...)
try:
 from transformers import BeamSearchScorer
except Exception:
 from transformers.generation.beam_search import BeamSearchScorer
# keep the rest of the imports as they were

• Caveats: modifying package files is less maintainable across upgrades. Prefer the runtime shim if you want a temporary fix.

Runtime shim and minimal source patch (copy-paste)

Non-invasive shim (paste at top of your script):

# place before any TTS import
try:
 from transformers import BeamSearchScorer
except Exception:
 try:
 from transformers.generation.beam_search import BeamSearchScorer
 except Exception:
 BeamSearchScorer = None
 if BeamSearchScorer:
 import transformers as _transformers
 setattr(_transformers, "BeamSearchScorer", BeamSearchScorer)

# then:
from TTS.api import TTS

If you prefer editing the installed package, open:
venv/lib/python3.11/site-packages/TTS/tts/layers/xtts/stream_generator.py
and wrap the BeamSearchScorer import as shown above. After changing package files, restart your Python process.

Minimal reproducible environment (Python + package versions)

If you want a clean environment that avoids the error entirely, use these concrete versions (proven-safe example):

• OS: Linux
• Python: 3.11 (supported; TTS requires >=3.9 and <3.12 — see setup.py)
• TTS (Coqui): 0.25.3
• transformers: 4.46.2
• torch: 2.2.2 (or any torch >=2.1 matching your CUDA / CPU)
• torchaudio: 2.2.2 (match torch)
• soundfile, librosa, numpy: use the versions from TTS requirements (see requirements.txt)

Create it quickly:

python3.11 -m venv venv
source venv/bin/activate
pip install --upgrade pip
pip install "TTS==0.25.3" "transformers==4.46.2" "torch==2.2.2" "torchaudio==2.2.2" soundfile librosa

Adjust torch/torchaudio for your CUDA version (or install CPU-only wheels if needed).

Validation & how to test the fix

1. Verify transformers exposes BeamSearchScorer:

python - <<'PY'
import transformers
print("transformers:", transformers.__version__)
print("has BeamSearchScorer top-level:", hasattr(transformers, "BeamSearchScorer"))
try:
 from transformers import BeamSearchScorer
 print("top-level import OK")
except Exception as e:
 print("top-level failed:", e)
PY

2. Run your original test script (the README example). If you applied the shim, ensure it’s at the top of the file.

3. If you still get errors, confirm TTS and transformers versions:

• pip show TTS
• pip show transformers

4. If problems persist, try installing the known-good pinned set inside a fresh venv (see commands above) and re-run.

Sources

• Coqui TTS stream_generator source (shows top-level import used by xtts_v2): https://raw.githubusercontent.com/coqui-ai/TTS/main/TTS/tts/layers/xtts/stream_generator.py
• Coqui TTS requirements.txt (transformers floor; torch requirement): https://raw.githubusercontent.com/coqui-ai/TTS/main/requirements.txt
• Coqui TTS setup.py (Python version constraint / install_requires): https://raw.githubusercontent.com/coqui-ai/TTS/main/setup.py
• Coqui TTS issue showing a similar ImportError (LogitsWarper): https://github.com/coqui-ai/TTS/issues/4165
• Community issue mentioning pinned transformers ranges for a TTS release: https://github.com/idiap/coqui-ai-TTS/issues/306
• Coqui TTS issue where users report various transformers versions: https://github.com/coqui-ai/TTS/issues/4290
• Hugging Face transformers issue about importing regressions in dev/major releases: https://github.com/huggingface/transformers/issues/42352

Conclusion

This ImportError for BeamSearchScorer when loading Coqui TTS xtts_v2 is caused by a transformers API / export mismatch. Easiest reliable fix: install a compatible transformers (for example, transformers==4.46.2 paired with TTS==0.25.3) or use the short runtime shim shown above to map the class from the submodule into transformers at import time. Pick the downgrade for stability, or the shim for a quick, reversible workaround.