{"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":"python","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,"search_vec":"'2.5.4':83 '2024':96 'activ':15,88 'api':35 'audio':41,102 'cli':23,106 'command':20 'command-lin':19 'continu':85 'convert':37 'current':81 'customiz':63 'enabl':70 'featur':61 'file':49,55 'file-lik':54 'flexibl':71 'generat':77 'googl':2,8,28,104 'google-transl':103 'gtts':1,7 'interact':26 'interfac':22 'latest':92 'librari':17,59 'like':56 'line':21 'maintain':89 'mp3':48 'natur':74 'natural-sound':73 'novemb':95 'object':57 'pre':66 'pre-process':65 'process':67 'provid':60 'python':16 'releas':93 'save':45 'sound':75 'speech':6,12,34,76,100 'spoken':40 'stream':51 'text':4,10,32,38,64,98 'text-to-speech':3,9,31,97 'token':69 'tool':24 'translat':29,105 'tts':101 'version':82","created_at":"2026-04-11T09:15:11.213369+00:00","updated_at":"2026-04-16T15:30:40.104285+00:00","problems":[{"fix":"Ensure `gtts` is installed for the correct Python interpreter by running: `pip install gtts` or `pip3 install gtts`.","cause":"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.","error":"ModuleNotFoundError: No module named 'gtts'"},{"fix":"Rename your Python script file to something other than `gtts.py` (e.g., `my_tts_app.py`).","cause":"This usually happens when your Python script file is named `gtts.py`, causing a conflict with the installed `gtts` library during the import statement.","error":"ImportError: cannot import name 'gTTS' from partially initialized module 'gtts' (most likely due to a circular import)"},{"fix":"Upgrade both `gtts` and `gtts-token` to their latest versions: `pip install --upgrade gtts gtts-token`.","cause":"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.","error":"AttributeError: 'NoneType' object has no attribute 'group'"},{"fix":"Reduce 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.","cause":"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.","error":"gtts.tts.gTTSError: 429 (Too Many Requests) from TTS API."},{"fix":"Ensure `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`.","cause":"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.","error":"'gtts-cli' is not recognized as an internal or external command"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"2.5.4","cli_name":"gtts-cli","cli_version":"gtts-cli, version 2.5.4","type":"library","homepage":null,"github":"https://github.com/pndurette/gTTS","docs":"https://gtts.readthedocs.io","changelog":"https://github.com/pndurette/gTTS/blob/main/CHANGELOG.md","pypi":"https://pypi.org/project/gtts/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["ai-ml","communication"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-28","next_check":"2026-07-28","install_tag":null}}