Install & Compatibility
Where this runs
tested against v2.5.4 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.380s · 22MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 2.3s · import 0.356s · 23MB
20MB installed
● package 20MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
gTTS
✓ from gtts import gTTS
This quickstart demonstrates how to initialize `gTTS` with a string and a language, then save the generated speech as an MP3 file. The `slow` parameter can be set to `True` for slower speech.
from gtts import gTTS
# The text that you want to convert to audio
text_to_speak = "Hello world, this is a test of the gTTS library."
# Language in which you want to convert
language = 'en'
# Pass the text and language to the gTTS object
tts = gTTS(text=text_to_speak, lang=language, slow=False)
# Save the converted audio to a file
tts.save("hello_world.mp3")
print("Audio saved as hello_world.mp3")
gtts-cli --version
Debug
Known issues
breakinggTTS relies on an undocumented Google Translate API, meaning breaking upstream changes can occur without notice from Google, potentially causing the library to malfunction.fixMonitor for updates and new releases of gTTS to incorporate fixes for upstream API changes. Report issues to the gTTS GitHub repository.
affects: All versions
gotchaAn active internet connection is strictly required for gTTS to function, as it sends text to Google's servers for audio generation.fixEnsure the environment where gTTS is run has a stable internet connection. Offline operation is not supported.
affects: All versions
breakingPrior to version 2.0, gTTS attempted to fetch language lists dynamically. As of gTTS 2.x, languages are pre-generated and shipped with the library, removing the automatic download feature which had become unreliable.fixUpgrade to gTTS >=2.0 for more reliable language support. If custom language handling was implemented, review `gtts.lang` for supported options.
affects: <2.0 (dynamic language fetching), >=2.0 (pre-generated languages)
deprecatedThe `debug` parameter of the `gTTS` constructor was removed in favor of Python's standard `logging` module (around gTTS 2.0).fixReplace usage of the `debug` parameter with Python's standard `logging` configuration. Import `logging` and configure the 'gtts' logger directly.
affects: <2.0 (debug parameter), >=2.0 (logging module)
breakingFor the `gtts-cli` command-line tool, the long option name for specifying the output file was changed from `--destination` to `--output` (around gTTS 2.0).fixUpdate CLI scripts to use `--output` instead of `--destination` when specifying the output file path for `gtts-cli`.
affects: <2.0 (--destination), >=2.0 (--output)
breakingSince gTTS 2.0, `gTTS()` will raise a `ValueError` instead of an `AssertionError` for unsupported languages when `lang_check` is enabled (which is the default behavior).fixUpdate error handling code to catch `ValueError` instead of `AssertionError` when dealing with potentially unsupported language codes. Refer to `gtts.lang.tts_langs()` for a list of supported languages.
affects: <2.0 (AssertionError), >=2.0 (ValueError)
gotchaWhile gTTS automatically handles long texts by tokenizing them, the underlying Google Translate API has a character limit for individual segments (typically around 100 characters). Very complex or extremely long single 'tokens' might still encounter issues, though this is rare with gTTS's built-in tokenizers.fixFor exceptionally long or complex single phrases, consider breaking them down manually or reviewing `gtts` tokenization options (`pre_processor_funcs`, `tokenizer_func`) for advanced control.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'gtts'
This error occurs when the `gtts` package is not installed in the Python environment being used, or the Python interpreter cannot find it in its search paths.
fixEnsure `gtts` is installed for the correct Python interpreter by running: `pip install gtts` or `pip3 install gtts`.
ImportError: cannot import name 'gTTS' from partially initialized module 'gtts' (most likely due to a circular import)
This usually happens when your Python script file is named `gtts.py`, causing a conflict with the installed `gtts` library during the import statement.
fixRename your Python script file to something other than `gtts.py` (e.g., `my_tts_app.py`).
AttributeError: 'NoneType' object has no attribute 'group'
This error often indicates an issue with an outdated version of `gtts` or its dependency `gtts-token`, or sometimes an invalid input text being passed to the `gTTS` constructor.
fixUpgrade both `gtts` and `gtts-token` to their latest versions: `pip install --upgrade gtts gtts-token`.
gtts.tts.gTTSError: 429 (Too Many Requests) from TTS API.
This error means you have sent too many requests to the Google Text-to-Speech API in a short period, triggering a rate limit. The gTTS library acts as a wrapper for this API, which has usage quotas.
fixReduce the frequency of your API calls, introduce delays between requests (e.g., `time.sleep()`), or consider if your usage patterns exceed fair use limits for the unofficial API.
'gtts-cli' is not recognized as an internal or external command
This error indicates that the `gtts-cli` command-line tool's executable path is not included in your system's PATH environment variable, or the tool was not installed correctly.
fixEnsure `gtts` is installed by `pip install gtts`. If it is, you might need to locate the `gtts-cli` executable in your Python's `Scripts` directory (on Windows) or `bin` directory (on Linux/macOS) and either add it to your PATH or call it directly using `python -m gtts_cli`.
Upgrade
Version history
2.5.4latest on PyPI · released Nov 10, 2024
Audit
Dependencies
No dependency data recorded yet.