ModuleNotFoundError / No module named 'whisper.__main__'
ModuleNotFoundError: No module named 'whisper' or 'whisper.__main__'
Stack trace
$ python -m whisper audio.mp3 --model base
/usr/bin/python3: No module named whisper
--- OR ---
$ python -m whisper audio.mp3
Traceback (most recent call last):
File "/usr/lib/python3.9/runpy.py", line 197, in _run_module_as_main
return _run_module_code(code, init_globals, None,
File "/usr/lib/python3.9/runpy.py", line 187, in _run_module_code
exec(code, run_globals)
File "/usr/local/lib/python3.9/dist-packages/whisper/__main__.py", line 1, in <module>
from whisper.cli import main
ModuleNotFoundError: No module named 'whisper'
--- OR (venv issue) ---
$ which python
/usr/bin/python3
$ which whisper
/home/user/.venv/bin/whisper
# whisper is in venv, but python is system python Why it happens
The openai-whisper package provides a CLI entry point via `python -m whisper`, but this requires the package to be installed in the active Python environment. Common causes: the package was never installed, installed globally but you're using a virtual environment, installed in a different Python version, or the installation was incomplete. Python's module discovery system cannot find the whisper package in sys.path, so the `-m` flag fails to locate `whisper/__main__.py`.
Detection
Before running `python -m whisper`, verify the installation with `pip show openai-whisper` and confirm the package location matches your active Python interpreter. Run `which python` and `which pip` to ensure they point to the same environment. Check `python -c 'import whisper; print(whisper.__file__)'`: if it fails, the package is not installed in your active environment.
Causes & fixes
openai-whisper package is not installed at all
Run `pip install openai-whisper` in your active Python environment. Verify with `pip show openai-whisper` and confirm the Location path contains your current Python's site-packages directory.
Package installed globally but you're running code in a virtual environment with a different Python
Activate your virtual environment with `source venv/bin/activate` (Linux/Mac) or `venv\Scripts\activate` (Windows), then run `pip install openai-whisper` again in that venv. Never mix global and venv Python installations.
Using a system python (e.g., /usr/bin/python3) but whisper is installed only in a venv or user environment
Use the exact Python interpreter where whisper is installed: `/path/to/venv/bin/python -m whisper audio.mp3` or activate the venv first with `source /path/to/venv/bin/activate`, then run `python -m whisper audio.mp3`.
Package installed in Python 3.9 but you have Python 3.11+ as system default, or vice versa
Install whisper in the exact Python version you're using: `python3.11 -m pip install openai-whisper` (replace 3.11 with your version). Check your Python version with `python --version` and install whisper for that specific version.
Code: broken vs fixed
#!/usr/bin/env python3
# Broken: relies on CLI being in PATH, but package not installed
import subprocess
import os
# This will fail with: ModuleNotFoundError: No module named 'whisper'
result = subprocess.run(['python', '-m', 'whisper', 'audio.mp3', '--model', 'base'],
capture_output=True, text=True)
if result.returncode != 0:
print(f"Error: {result.stderr}")
else:
print(result.stdout)#!/usr/bin/env python3
# Fixed: verify installation and use the correct Python environment
import subprocess
import sys
import os
# STEP 1: Verify whisper is installed in the active environment
try:
import whisper
print(f"✓ Whisper installed at: {whisper.__file__}")
except ModuleNotFoundError:
print(f"✗ Whisper not found in {sys.executable}")
print(f" Install with: {sys.executable} -m pip install openai-whisper")
sys.exit(1)
# STEP 2: Use the current Python interpreter explicitly
audio_file = 'audio.mp3'
model = 'base'
result = subprocess.run([sys.executable, '-m', 'whisper', audio_file, '--model', model],
capture_output=True, text=True)
if result.returncode == 0:
print(f"✓ Transcription successful")
print(result.stdout)
else:
print(f"✗ Error: {result.stderr}")
sys.exit(1)Workaround
If you cannot install openai-whisper via pip (e.g., in a restricted environment), use the OpenAI API instead: `client.audio.transcriptions.create(model='whisper-1', file=open('audio.mp3', 'rb'))` from the OpenAI SDK (requires API key but no local installation). Alternatively, transcribe programmatically with the whisper library directly in Python: `import whisper; model = whisper.load_model('base'); result = model.transcribe('audio.mp3')`: this bypasses the CLI entirely and still works if the package is installed.
Prevention
Always verify your Python environment before running CLI commands: use virtual environments consistently (never mix global and venv Python), pin your openai-whisper version in requirements.txt or pyproject.toml, and add a startup check in scripts that verifies the package is importable. For production deployments, use Docker to guarantee a consistent Python environment with all dependencies pre-installed, eliminating environment-mismatch errors completely.