{"id":2965,"library":"gtts","title":"gTTS (Google Text-to-Speech)","description":"gTTS (Google Text-to-Speech) is an active Python library and command-line interface (CLI) tool that interacts with Google Translate's text-to-speech API. It converts text into spoken audio, which can be saved as an MP3 file or streamed to a file-like object. The library provides features for customizable text pre-processing and tokenization, enabling flexible and natural-sounding speech generation. As of its current version, 2.5.4, it continues to be actively maintained, with its latest release in November 2024.","status":"active","version":"2.5.4","language":"en","source_language":"en","source_url":"https://github.com/pndurette/gTTS","tags":["text-to-speech","tts","audio","google-translate","cli"],"install":[{"cmd":"pip install gTTS","lang":"bash","label":"Install gTTS"}],"dependencies":[],"imports":[{"symbol":"gTTS","correct":"from gtts import gTTS"}],"quickstart":{"code":"from gtts import gTTS\n\n# The text that you want to convert to audio\ntext_to_speak = \"Hello world, this is a test of the gTTS library.\"\n\n# Language in which you want to convert\nlanguage = 'en'\n\n# Pass the text and language to the gTTS object\ntts = gTTS(text=text_to_speak, lang=language, slow=False)\n\n# Save the converted audio to a file\ntts.save(\"hello_world.mp3\")\n\nprint(\"Audio saved as hello_world.mp3\")","lang":"python","description":"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."},"warnings":[{"fix":"Monitor for updates and new releases of gTTS to incorporate fixes for upstream API changes. Report issues to the gTTS GitHub repository.","message":"gTTS relies on an undocumented Google Translate API, meaning breaking upstream changes can occur without notice from Google, potentially causing the library to malfunction.","severity":"breaking","affected_versions":"All versions"},{"fix":"Ensure the environment where gTTS is run has a stable internet connection. Offline operation is not supported.","message":"An active internet connection is strictly required for gTTS to function, as it sends text to Google's servers for audio generation.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade to gTTS >=2.0 for more reliable language support. If custom language handling was implemented, review `gtts.lang` for supported options.","message":"Prior 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.","severity":"breaking","affected_versions":"<2.0 (dynamic language fetching), >=2.0 (pre-generated languages)"},{"fix":"Replace usage of the `debug` parameter with Python's standard `logging` configuration. Import `logging` and configure the 'gtts' logger directly.","message":"The `debug` parameter of the `gTTS` constructor was removed in favor of Python's standard `logging` module (around gTTS 2.0).","severity":"deprecated","affected_versions":"<2.0 (debug parameter), >=2.0 (logging module)"},{"fix":"Update CLI scripts to use `--output` instead of `--destination` when specifying the output file path for `gtts-cli`.","message":"For 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).","severity":"breaking","affected_versions":"<2.0 (--destination), >=2.0 (--output)"},{"fix":"Update 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.","message":"Since 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).","severity":"breaking","affected_versions":"<2.0 (AssertionError), >=2.0 (ValueError)"},{"fix":"For exceptionally long or complex single phrases, consider breaking them down manually or reviewing `gtts` tokenization options (`pre_processor_funcs`, `tokenizer_func`) for advanced control.","message":"While 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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}