How to Upgrade OpenSuperWhisper to the Latest Version: 3 Methods Explained

You can upgrade OpenSuperWhisper to the latest version using Homebrew (brew upgrade opensuperwhisper) for stable releases, or by pulling the latest commit and running ./run.sh build if you need unreleased features or custom builds.

OpenSuperWhisper is a macOS-native speech-to-text application that wraps OpenAI's Whisper model in a Swift interface. Whether you initially installed it via Homebrew or built it manually from the Starmel/OpenSuperWhisper repository, maintaining the latest version ensures access to transcription improvements and stability fixes. This guide covers three distinct approaches to upgrade OpenSuperWhisper to the latest version, from one-line terminal commands to complete source rebuilds.

Method 1: Upgrade via Homebrew (Recommended)

The fastest and safest way to upgrade OpenSuperWhisper to the latest version is through Homebrew, which automatically fetches the newest release DMG and installs it in /Applications.

Prerequisites

• Homebrew installed on your macOS system

Upgrade Steps

Run the following commands in Terminal:

# Refresh the formulae index

brew update

# Upgrade to the latest released version

brew upgrade opensuperwhisper

Why this works: The Homebrew formula points to the latest GitHub tag (e.g., 0.0.4). When you run brew upgrade, it downloads the official release artifact and replaces the existing application in your system. This process is documented in the repository's README.md under the Installation section.

Method 2: Build from Source for the Latest Commits

Use this method when you need the absolute latest unreleased changes, want to modify build flags, or are contributing to the Starmel/OpenSuperWhisper project.

Prerequisites

Install the required build dependencies:

brew install cmake libomp rust ruby
gem install xcpretty  # Optional, for prettier Xcode build output

Step 1: Pull the Latest Changes

Navigate to your local repository and update the code:

cd OpenSuperWhisper
git pull
git submodule update --init --recursive

If you don't have a local copy yet, clone it fresh:

git clone https://github.com/Starmel/OpenSuperWhisper.git
cd OpenSuperWhisper
git submodule update --init --recursive

Step 2: Execute the Build Script

Run the helper script that orchestrates the entire compilation process:

./run.sh build

What the script does: According to the source in run.sh (lines 8-50), this command configures the native Whisper C++ library (libwhisper), compiles the Swift autocorrect wrapper via Cargo, copies required dynamic libraries like libomp.dylib, and invokes xcodebuild to generate the application bundle.

Step 3: Optional Notarization and DMG Creation

If you need a signed DMG for distribution or prefer installing a notarized app, run:

./notarize_app.sh "Developer ID Application: YOUR NAME (TEAM_ID)"

This script handles code signing, notarization with Apple, and DMG packaging. After completion, mount OpenSuperWhisper.dmg and drag the app to /Applications as documented in docs/release_build.md.

Method 3: Publish a New Release (Maintainers Only)

If you are the maintainer releasing a new official version, use the automated release script to bump version numbers, build, sign, and publish.

Automated Version Bump and Release

Run the release script with your code signing identity and GitHub token:

./make_release.sh 0.0.5 "Developer ID Application: YOUR NAME (TEAM_ID)" <YOUR_GITHUB_TOKEN>

What happens: The script updates MARKETING_VERSION and CURRENT_PROJECT_VERSION in OpenSuperWhisper.xcodeproj/project.pbxproj (lines 51-62 of make_release.sh), builds the application, creates a signed DMG, generates a Git tag, and optionally attaches the DMG to a GitHub release.

Summary

• Homebrew users should run brew update && brew upgrade opensuperwhisper for the fastest, most stable upgrade path
• Developers and power users must pull the latest commit, update submodules with git submodule update --init --recursive, and execute ./run.sh build to compile from source
• Maintainers use ./make_release.sh to automate version bumps, notarization, and GitHub releases
• Key files involved in the upgrade process include run.sh (build logic), make_release.sh (release automation), and notarize_app.sh (code signing)

Frequently Asked Questions

How do I check which version of OpenSuperWhisper is currently installed?

On macOS, right-click the OpenSuperWhisper app in /Applications, select Get Info, and check the Version field. Alternatively, if you installed via Homebrew, run brew list opensuperwhisper --versions to see the installed version number. The version corresponds to the MARKETING_VERSION set in OpenSuperWhisper.xcodeproj/project.pbxproj.

Can I upgrade OpenSuperWhisper without reinstalling Homebrew?

Yes, you can upgrade without Homebrew by building from source. Delete the existing app from /Applications, pull the latest changes from the repository, and run ./run.sh build to compile the new version. This method bypasses the Homebrew ecosystem entirely while ensuring you have the latest commits.

What should I do if the build fails after pulling the latest source?

First, ensure all dependencies are current by running brew install cmake libomp rust ruby and updating submodules with git submodule update --init --recursive. If compilation still fails, check that you have Xcode Command Line Tools installed (xcode-select --install). The build process defined in run.sh requires these tools to compile the Swift wrapper and Whisper C++ library.

Do I need to notarize the app when building from source for personal use?

No, notarization is only required if you intend to distribute the application to other users or install it on multiple machines with Gatekeeper restrictions. For personal development use, the app built via ./run.sh build runs locally without notarization. Use ./notarize_app.sh only when you need a signed DMG for distribution.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}