Install & Compatibility
Where this runs
tested against v2.99 · 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
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to initialize the `pyttsx3` engine, adjust common properties like speech rate and volume, select a specific voice, queue multiple text utterances, and then process them using `runAndWait()`. It also shows how to stop the engine gracefully.
import pyttsx3
# Initialize the TTS engine
engine = pyttsx3.init()
# Get current speech rate and set a new one
rate = engine.getProperty('rate')
print(f"Current speaking rate: {rate}")
engine.setProperty('rate', 150) # words per minute
# Get current volume and set a new one (0.0 to 1.0)
volume = engine.getProperty('volume')
print(f"Current volume: {volume}")
engine.setProperty('volume', 0.9)
# Get available voices and set a female voice (if available)
voices = engine.getProperty('voices')
for voice in voices:
if 'female' in voice.name.lower(): # Or check voice.id for specific IDs
engine.setProperty('voice', voice.id)
break
# Queue text to be spoken
engine.say("Hello, welcome to pyttsx3!")
engine.say("I can speak at different rates and volumes.")
# Process the speech queue and wait for it to finish
engine.runAndWait()
# Save speech to a file (requires espeak-ng on Linux to save to MP3/WAV, or other OS native capabilities)
# engine.save_to_file('Hello World', 'output.mp3')
# engine.runAndWait()
# Stop the engine when done
engine.stop()
Debug
Known issues
gotchaThe `engine.runAndWait()` method is crucial for speech output. If not called, queued `engine.say()` commands will not be processed, or only the first message might be spoken before the script exits. It blocks until all queued speech is complete. In GUI applications, consider running speech in a separate thread to prevent the UI from freezing.fixAlways call `engine.runAndWait()` after queuing speech with `engine.say()`. For multiple `say()` calls, queue all then call `runAndWait()` once, or call `runAndWait()` after each `say()` for sequential, blocking output. For non-blocking behavior in GUIs, run the TTS operations in a dedicated thread.
affects: All versions
gotchaPlatform-specific dependencies are often required beyond `pip install pyttsx3`. On Windows, `pywin32` is frequently needed. On Linux, system packages like `espeak-ng` or `espeak` and `libespeak1` are mandatory. On macOS, `pyobjc` might be necessary for some environments or Python versions, specifically `pyobjc>=9.0.1`.fixConsult the `pyttsx3` documentation or `pip` output for platform-specific installation instructions if you encounter 'No engine could be found' or driver initialization errors. Install `pywin32` via `pip` on Windows, `espeak-ng` and `libespeak1` via your system's package manager on Linux, and potentially `pyobjc` via `pip` on macOS.
affects: All versions
breakingRecent versions of pyttsx3 (e.g., 2.99) have explicitly removed Python 2 compatibility code, making them Python 3-only. Projects relying on older `pyttsx3` versions in a Python 2 environment will break if upgraded to the latest `pyttsx3`.fixEnsure your project runs on Python 3. For legacy Python 2 projects, stick to older `pyttsx3` versions (e.g., 2.6) that explicitly stated Python 2 compatibility, or migrate your project to Python 3.
affects: v2.99 and later (Python 2 compatibility removed around v2.99)
gotchaIn versions prior to 2.95, the `engine.save_to_file()` method on macOS (Darwin platform using the NSSS driver) could produce empty audio files. While this was addressed in v2.95, users on older versions might still encounter this bug.fixUpgrade to `pyttsx3` v2.95 or newer if experiencing empty audio files when using `save_to_file()` on macOS. If upgrading is not an option, consider alternative methods for audio file generation or system-specific workarounds.
affects: Prior to v2.95
gotchaOccasional `ModuleNotFoundError` or driver initialization errors can occur due to incorrect Python environment setup (e.g., pip installing to a different Python interpreter than the one being run) or outdated `wheel` package. Using `python -m pip` can sometimes help.fixAlways use `python -m pip install pyttsx3` to ensure the package is installed for the correct Python interpreter. If installation errors persist, try `pip install --upgrade wheel` before installing `pyttsx3`. Consider using virtual environments to manage dependencies.
affects: All versions
Errors
Common errors & fixes
ImportError: No module named win32com.client
The `pywin32` library, essential for `pyttsx3` to use Windows SAPI5 for text-to-speech, is either not installed or not correctly configured.
fixInstall the `pywin32` library: `pip install pywin32`
RuntimeError: The audio object isn't ready, call engine.say() first.
The `engine.runAndWait()` method was called before any text was queued for speech using `engine.say()`, or after `engine.stop()` without new `say()` calls.
fixEnsure `engine.say()` is called at least once to queue text before invoking `engine.runAndWait()` to process the speech.
ModuleNotFoundError: No module named 'pyttsx3'
The `pyttsx3` library has not been installed in your current Python environment or the interpreter cannot locate it.
fixInstall the library using pip: `pip install pyttsx3`
AttributeError: 'NoneType' object has no attribute 'say'
The `pyttsx3.init()` function failed to create and return a valid speech engine object, likely due to missing underlying TTS components on the operating system.
fixEnsure required backend speech synthesis components are installed for your OS (e.g., `pip install pywin32` on Windows, `sudo apt-get install espeak` on Debian/Ubuntu, `brew install espeak` on macOS) and verify system audio drivers.
Upgrade
Version history
2.99latest on PyPI · released Jul 8, 2025
Audit
Dependencies
pywin32optionalOften required for the SAPI5 driver to function correctly on Windows, especially in virtual environments or specific system configurations.
espeak-ngoptionalThe underlying TTS engine for Linux. Needs to be installed at the system level (e.g., via apt, dnf, pacman). `espeak` is an older alternative.
pyobjcoptionalMay be required for the NSSpeechSynthesizer driver on macOS, particularly for older Python versions or specific setups. Version `9.0.1` or higher is sometimes recommended.