Getting started

This page walks through installing the package, running the CLI on an audio file, and using the Python API. Most of this is condensed from the project's README.md — it is repeated here so you can get going without leaving the wiki.

Prerequisites

• Python: 3.8 to 3.13 (pyproject.toml lists 3.8–3.13 in the classifiers; CI tests 3.8–3.13 in .github/workflows/test.yml).
• PyTorch: any reasonably recent version. CI matrix runs 1.10.1, 1.13.1, 2.0.1, 2.1.2, 2.2.2, 2.3.1, 2.4.1, 2.5.1.
• ffmpeg in PATH. The audio loader shells out to it directly — see cmd = ["ffmpeg", ...] in whisper/audio.py.
• CUDA + Triton (optional, x86_64 Linux only): used for the GPU DTW and median-filter kernels in whisper/triton_ops.py. Without it, word timestamps fall back to the CPU/Numba implementation.
• Rust toolchain (only sometimes): if tiktoken does not have a prebuilt wheel for your platform, pip will compile it from source. See the README for setuptools-rust instructions.

Install

From PyPI:

pip install -U openai-whisper

From source (the latest commit on main):

pip install git+https://github.com/openai/whisper.git

For development:

git clone https://github.com/openai/whisper.git
cd whisper
pip install -e .[dev]   # adds black, flake8, isort, pytest, scipy

The dev extra is defined in pyproject.toml.

CLI quickstart

The default model is turbo, which is large-v3 distilled for speed.

whisper audio.flac audio.mp3 audio.wav --model turbo

The CLI writes one transcript per input file in --output_dir (default .) in every supported format (txt, vtt, srt, tsv, json). Pick one with --output_format to skip the rest.

For non-English audio you can let the model auto-detect or force a language:

whisper japanese.wav --language Japanese

Translate non-English speech into English (use a multilingual non-turbo model for translation):

whisper japanese.wav --model medium --language Japanese --task translate

See Reference: configuration for every CLI flag. whisper --help prints the full list.

Python quickstart

import whisper

model = whisper.load_model("turbo")
result = model.transcribe("audio.mp3")
print(result["text"])

result is a dict with text, segments (per-segment dicts with timestamps, tokens, log-probabilities, no-speech probabilities, and optionally words), and language.

For the lower-level decoding API on a single 30 s chunk:

import whisper

model = whisper.load_model("turbo")
audio = whisper.load_audio("audio.mp3")
audio = whisper.pad_or_trim(audio)
mel = whisper.log_mel_spectrogram(audio, n_mels=model.dims.n_mels).to(model.device)

# Detect language
_, probs = model.detect_language(mel)
print("Detected language:", max(probs, key=probs.get))

# Decode
options = whisper.DecodingOptions()
result = whisper.decode(model, mel, options)
print(result.text)

whisper.DecodingOptions is the dataclass defined in whisper/decoding.py. Common fields:

• task: "transcribe" or "translate" ("lang_id" is also accepted internally for language detection only).
• language: an ISO code or English name; if None, the model auto-detects.
• temperature, best_of, beam_size, patience, length_penalty: sampling controls.
• prompt, prefix: text or token IDs to bias the decoder.
• suppress_tokens, suppress_blank: logit suppression.
• without_timestamps, max_initial_timestamp: timestamp control.
• fp16: whether to run the encoder in half precision.

Model files and cache

whisper.load_model("turbo") downloads the checkpoint into ~/.cache/whisper (or $XDG_CACHE_HOME/whisper) on first use, verifying it against the SHA-256 fragment embedded in the URL. See _download() in whisper/__init__.py.

You can pass an explicit path to override the cache location with download_root=, or pass a path to a .pt file directly to load_model() to load a custom checkpoint that has the same {dims, model_state_dict} shape.

Running the tests

pip install -e .[dev]
pytest -m 'not requires_cuda'

CI restricts which transcribe-test cases run by model size:

pytest --durations=0 -vv \
  -k 'not test_transcribe or test_transcribe[tiny] or test_transcribe[tiny.en]' \
  -m 'not requires_cuda'

The audio fixture is a JFK clip at tests/jfk.flac. The CUDA-only equivalence tests (DTW and median filter) are marked @pytest.mark.requires_cuda — see Testing.

Troubleshooting

• ffmpeg not found — install ffmpeg (apt install ffmpeg, brew install ffmpeg, etc.). The audio loader executes the binary directly; the Python package ffmpeg-python is not used.
• No module named 'setuptools_rust' — pip install setuptools-rust, then re-run the whisper install. This only matters when tiktoken has no prebuilt wheel for your platform.
• Performing inference on CPU when CUDA is available — informational warning from transcribe(); pass device="cuda" to load_model() to use the GPU.
• FP16 is not supported on CPU; using FP32 instead — automatic fallback in transcribe(). To silence it, pass fp16=False explicitly.
• Failed to launch Triton kernels when computing word timestamps — the GPU path needs the Triton toolkit; the warning is benign because the code falls back to dtw_cpu / CPU median_filter.