Tooling

Build and packaging

The repository uses PEP 621 packaging via pyproject.toml. The build backend is setuptools.build_meta. The version is read dynamically from whisper/version.py (__version__). Versions follow a date-stamped scheme: YYYYMMDD, currently 20250625.

The console script whisper is registered to whisper.transcribe:cli. MANIFEST.in ensures the assets/ files (gpt2.tiktoken, multilingual.tiktoken, mel_filters.npz) are included in the sdist.

Build locally:

python -m build --sdist
# outputs dist/openai-whisper-<version>.tar.gz

Pre-commit hooks

Configured in .pre-commit-config.yaml. All hook revs are pinned to immutable commit hashes (the comment names the human-readable version):

Hook	What it does
check-json	Validates JSON files
end-of-file-fixer	Adds a trailing newline (Python files only)
trailing-whitespace	Strips trailing whitespace (Python files only)
mixed-line-ending	Normalizes line endings
check-added-large-files	Rejects new files larger than 4 MB
black	Auto-formats Python
isort	Sorts imports with --profile black
flake8	Lints Python with project-specific ignores

Install once with pre-commit install; CI also runs pre-commit run --all-files as the first job.

CI workflows

.github/workflows/test.yml runs on every push to main and every PR targeting main:

1. pre-commit job: caches pip + pre-commit, runs the full hook set on the whole repo.
2. whisper-test matrix: 9 Python × PyTorch combinations, on ubuntu-latest. Uses conda-incubator/setup-miniconda to install ffmpeg, installs the package with pip install .[dev] <numpy-pin> torch==<version>+cpu --index-url ... --extra-index-url ..., and runs the restricted pytest command.

.github/workflows/python-publish.yml runs only on pushes to main. It uses a regex action to match commit messages of the form Release vYYYYMMDD. On a match, it builds the sdist with python -m build, uploads to PyPI via twine, and creates a GitHub release tagged vYYYYMMDD.

.github/dependabot.yml enables weekly Dependabot scans for GitHub Actions, grouped into a single PR.

Local CLI

# Run from a checkout
python -m whisper --model tiny tests/jfk.flac
# or after `pip install -e .`
whisper --model tiny tests/jfk.flac

Useful flags during development:

• --verbose True — print decoded segments as they happen (default).
• --verbose False — quiet mode with a progress bar.
• --verbose None — fully silent.
• --fp16 False — force fp32 (required on CPU; the warning otherwise prints).
• --output_format json — single-format output is faster than all.

What is not in this repo

• No Makefile or task runner. pyproject.toml is the source of truth for dependencies; pre-commit is the source of truth for lint; pytest is the source of truth for tests.
• No Docker images, devcontainers, or build scripts.
• No code generation (the BPE merges and mel filterbanks are committed as binary assets, not generated at install time).
• No model conversion scripts. Checkpoints are plain torch.save({"dims", "model_state_dict"}, ...).