Development workflow

Set up your environment

git clone https://github.com/openai/whisper.git
cd whisper
python -m venv .venv && source .venv/bin/activate
pip install -e .[dev]
pre-commit install

The dev extra in pyproject.toml pulls in black, flake8, isort, pytest, and scipy. pre-commit install adds the project's hooks (configured in .pre-commit-config.yaml) to your local git.

You'll also need ffmpeg on your PATH to run the test suite (the JFK fixture is a .flac file decoded via ffmpeg).

Branch, edit, run

1. Make a topic branch off main.
2. Edit; iterate locally.
3. Run targeted tests as you go (pytest tests/test_audio.py, pytest tests/test_normalizer.py, etc.).
4. Run the full lint pass: pre-commit run --all-files.
5. Run the full local test suite: pytest -m 'not requires_cuda'.

Commit messages

The history shows a few conventions:

• Bug fixes: Fix: <short description> (#<PR>) or Bugfix: <description>.
• Docs: docs: <description> or Update README.md.
• Releases: Release vYYYYMMDD (this format is matched by the publish workflow's regex).
• Mechanical updates: free-form, e.g. pre-commit autoupdate && pre-commit run --all-files.

There is no enforced format. Prefer short, descriptive messages with a PR number suffix when one exists.

Open a PR

Push the branch and open a PR against openai/whisper:main. CI runs the pre-commit job first, then the whisper-test matrix, which spans Python 3.8–3.13 and PyTorch 1.10.1–2.5.1 (.github/workflows/test.yml).

The matrix runs on ubuntu-latest with conda-incubator/setup-miniconda (used to install ffmpeg) and a CPU-only PyTorch build pulled from the PyTorch wheels index.

The CI's pytest invocation:

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

This restricts the (heavy) end-to-end transcribe test to the tiny and tiny.en models so the matrix finishes in reasonable time. Other tests run without restriction.

After review

• Squash and merge is the norm; the PR title becomes the commit message.
• Releases are cut by maintainers by landing a commit titled Release vYYYYMMDD on main — this triggers python-publish.yml to upload to PyPI and create a GitHub release.

Common local tasks

Task	Command
Run all CPU tests	pytest -m 'not requires_cuda'
Run only normalizer tests	pytest tests/test_normalizer.py
Run a specific transcribe test	pytest tests/test_transcribe.py -k tiny.en
Check formatting	pre-commit run black --all-files
Check imports	pre-commit run isort --all-files
Check style	pre-commit run flake8 --all-files
Run the CLI from your checkout	python -m whisper --model tiny tests/jfk.flac