gTTS: a Python wrapper around Google Translate's speech endpoint

What gTTS actually is, and who reaches for it

gTTS is a thin client. The README describes it as a Python library and CLI tool to interface with Google Translate's text-to-speech API, and the disclaimer is blunt about the rest: the project is not affiliated with Google or Google Cloud, and it is leveraging the undocumented Google Translate speech functionality. That single sentence defines both the appeal and the risk.

The people who reach for it are usually not building a voice product. They are generating narration for a video pipeline, producing audio versions of articles or documentation, making pronunciation clips for a language app, or adding a spoken confirmation to a script. In all of those cases the requirement is the same: hand over a string, get back an MP3. gTTS does that in two lines of Python, and the CLI does it in one.

The feature list is short, and the two items on it are the interesting ones. There is a speech-specific sentence tokenizer that the README says allows for unlimited lengths of text to be read while keeping proper intonation, abbreviations and decimals. There are also customizable text pre-processors, which the README gives the example of pronunciation corrections. Those two features are the difference between gTTS and a raw HTTP call to the same endpoint.

How the tokenizer and pre-processors shape the request

The endpoint behind Google Translate's speech function takes a bounded chunk of text and returns audio. So any long input has to be split, and the quality of the split decides whether the result sounds like speech or like a list of fragments. gTTS puts a tokenizer in front of the request for exactly that reason: it breaks text at sentence boundaries rather than at a fixed character count, which is why the README can claim intonation survives long inputs.

Pre-processors run before that. The README describes them as a way to apply pronunciation corrections, so the pipeline is text in, pre-processor transforms, tokenizer splits, requests go out, MP3 data comes back. The output side is equally explicit: the README says gTTS writes spoken mp3 data to a file, a file-like object as a bytestring for further audio manipulation, or stdout. That bytestring option is what makes it usable inside a larger audio pipeline rather than only as a file generator.

What is not in the README is a description of retry behaviour, rate limiting, or how the library handles a change in the upstream response format. The disclaimer says breaking upstream changes can occur without notice, which is a fair warning but not a mitigation. If you are generating thousands of clips, you are responsible for the pacing and the error handling around it.

Installing gTTS and producing a first MP3

Installation is a single pip command. The README gives it without options or extras, and the package name on PyPI is gTTS with that capitalization.

pip install gTTS

The project metadata requires Python 3.7 or later, and the classifiers list 3.8 through 3.12. Dependencies are pinned by range: requests >=2.27, <3 and click >=7.1, <8.2. The click upper bound is worth noticing if your environment already pins a newer click for another tool; pip will have to resolve that conflict.

The CLI entry point is gtts-cli. The README example writes a file named hello.mp3 in the current directory.

gtts-cli 'hello' --output hello.mp3

The module path is just as short. You construct a gTTS object and call save.

from gtts import gTTS
tts = gTTS('hello')
tts.save('hello.mp3')

After either of those, hello.mp3 should exist and play as the word hello. If you want the audio in memory instead of on disk, the README states that a file-like object (bytestring) is a supported output, which is the route to take when the next step is mixing or transcoding rather than storage. Note that the README does not document a language argument in the quickstart; the documentation site at gtts.readthedocs.io is where the examples for that live.

The undocumented dependency is the real limitation

The disclaimer is the most important paragraph in the repository. It says the project is not affiliated with Google or Google Cloud, that breaking upstream changes can occur without notice, and that it is different from Google Cloud Text-to-Speech. Read that as an architecture statement: gTTS has no contract with the service it calls.

The practical consequences are concrete. There is no supported voice list, no SSML input, no pitch or speaking-rate control exposed in the README, and no guarantee that a given language or accent will keep working. A change on the Translate side can break generation for everyone at once, and the fix has to come from the maintainer or from you. The last push to the repository was on 2026-04-06, and the most recent release listed is v2.5.4 from 2024-11-10, so the project is not abandoned, but the release cadence is not a promise of same-day response to an upstream break either.

There is a second limitation that is easier to miss. The related searches include text-to-speech offline. gTTS is the opposite of that: every call goes to a remote service. If your requirement is offline synthesis, or a data path that cannot leave your network, gTTS is the wrong tool and no configuration will change that. The same applies to anyone who needs a commercial SLA or a support contract, because the README offers neither.

Where gTTS sits next to pyttsx3 and Google Cloud TTS

The honest comparison is against two different things.

Against pyttsx3, the difference is local versus remote. pyttsx3 wraps speech engines installed on the machine, which means it works without a network and produces audio immediately, but the voices and languages available are whatever the host has installed. gTTS reaches a remote endpoint, which is why it covers many languages without any local setup, and why it fails when the network or the endpoint does. If your users are offline, the comparison ends there.

Against Google Cloud Text-to-Speech, the difference is contract versus convenience. Cloud TTS is a documented, supported product with the controls you would expect from one. gTTS is, by its own README, built on the undocumented Translate speech functionality, and the README explicitly separates the two. You are trading features and support for a two-line install and no credentials. For a side project or an internal script, that trade is often correct. For anything with a support obligation attached, it usually is not.

The related searches also surface people pairing gTTS with moviepy, flask and playsound. Those are integration questions rather than alternatives: gTTS produces the MP3, and the other library consumes it. The playsound search in particular suggests users hitting version friction on the playback side, which is a reminder that gTTS only covers the synthesis step.

Licence, upgrade cost and what to check before you ship

The project is MIT licensed, Copyright 2014-2024 Pierre Nicolas Durette and contributors. That is permissive and imposes no obligations beyond keeping the licence notice. What MIT does not cover is the service on the other end. The code is yours to use freely; the endpoint it calls is somebody else's, undocumented, and outside any agreement you have with the gTTS authors. That is a factual boundary, not a legal opinion, and if the distinction matters to your organisation, it is worth putting in front of someone qualified to assess it.

Upgrade cost is low in the normal case. The public surface described in the README is two things: the gtts-cli command and the gTTS class with save. Releases move slowly, with v2.5.2, v2.5.3 and v2.5.4 spread across July, August and November 2024. The dependency ranges on requests and click are the main thing that can force a version bump in a locked environment.

The upgrade cost that is not low is the failure case. Because the upstream is undocumented, an upgrade can be forced on you by a change you did not make. Pin the version, keep the generation step behind a function you can swap, and test the languages you actually ship with rather than the one in the README.

Editorial conclusion

Use gTTS when you want a few lines of Python to produce MP3 speech files in many languages and you accept that the upstream endpoint is undocumented and can change without notice. Do not use it when you need a supported SLA, voice selection, SSML control, or offline synthesis: the README states this project is different from Google Cloud Text-to-Speech, and the related search phrase text-to-speech offline points at a need gTTS does not meet by design. Before adopting it, verify three things in your own environment: that the installed version is 2.5.4 or later, that your network path to translate.google.com is allowed, and that the languages and accents you need are still returned by the endpoint.

Frequently asked questions

Official sources

1. License: MIT
2. pndurette/gTTS on GitHub
3. Project website
4. README
5. Releases