Skip to content

Managed installations

Verified releases for Debian/Ubuntu, Fedora and openSUSE. AUR updates stay with your package manager; development checkouts keep their existing workflow.

Terminal window
hyprwhspr update
hyprwhspr update --version v1.2.3
hyprwhspr install status
hyprwhspr install repair
hyprwhspr install repair --python /absolute/path/to/python
hyprwhspr uninstall
hyprwhspr uninstall --purge
hyprwhspr uninstall --purge --keep-models

Updates reuse models and skip onboarding and host dependency installation. update --version can select an older supported release; settings must validate before activation. There is no retained instant rollback command. install auto remains an alias for automated setup.

Python 3.11–3.15 is required. ONNX and faster-whisper currently require Python 3.14 or earlier; select it with --python /path/to/python3.14. Setup reports an incompatible selection before replacing environments. Updates retain the recorded interpreter, falling back to a compatible system Python if it disappears. update --python PATH selects a replacement explicitly. Paths from uv, mise and pyenv work without activation; hyprwhspr never installs Python or changes manager settings.

Application releases and private CLI/backend environments live under $XDG_DATA_HOME/hyprwhspr. Receipts and recovery state live under $XDG_STATE_HOME/hyprwhspr. Both default to the usual ~/.local locations. Settings, credentials, models and IPC keep their existing locations.

The configuration directory is pinned at installation. To change it, run install repair from a session with the desired XDG_CONFIG_HOME.

Updates temporarily need space for both environments, downloads and build files. The 256 MiB staging minimum is not a build-size estimate; GPU builds need more. Unreferenced generations are removed after success. Files still in use are queued for later cleanup. Shared pip, uv and model caches are preserved.

Distro packages supply native libraries and desktop bindings. Host package changes are separate from application rollback.

Stop a manually launched daemon before updating. Managed services stop gracefully; only a previously running service restarts. Activation checks 15 seconds of stable startup within a 60-second window, not transcription accuracy.

Failed activation restores the previous generation. Interrupted operations recover on the next lifecycle command. install status reports pending cleanup, restoration jobs and retained recovery files without changing them.

  • Broken environment or payload: run install repair.
  • Backend rebuild: run backend repair; it uses the local payload, but Python dependencies may need downloading.
  • No usable Python or launcher: rerun bootstrap with --repair --python PATH.
  • Cleanup failure: correct the reported filesystem permissions, then retry repair. A new cleanup failure returns nonzero even when activation succeeded; subsequent commands warn and retry previously recorded failures.

Unreadable state is reported and preserved where possible. Unknown ownership or recovery references preserve files rather than authorizing deletion. Inspect paths listed by install status before deleting recovery evidence; it is not expired automatically. Failure to save recovery state retains the transaction journal.

An older installed launcher can reject the new system Python before hyprwhspr update runs. Bootstrap --repair without --version retains the installed application release, so it can select the same incompatible recovery helper. Select a published release that supports your new Python explicitly:

Terminal window
# Replace the placeholder with a published version supporting your Python.
curl -fsSL https://hyprwhspr.com/install.sh | bash -s -- \
--repair --version '<release-with-3.15-support>' --python /usr/bin/python3

Replace the entire <release-with-3.15-support> placeholder, including angle brackets, with the release tag from the release notes. This rebuilds the managed environments for the selected interpreter while preserving settings and models. If that release is not yet published, use an installed Python supported by the old release with --repair --python /absolute/path/to/python instead.

Migration recognizes the old ~/.local/share/hyprwhspr/src bootstrap checkout and builds replacement environments. It removes the checkout only after activation, with the expected upstream, no local changes or local-only commits, and no remaining desktop references. Python bytecode is disposable; uncertain content is preserved.

Recognized services, bindings and bar integrations move to stable launcher paths. Customized files are preserved with guidance. Restart bars still using an old configuration, reconcile reported references, then retry cleanup.

Uninstall preserves settings, credentials and models. --purge removes only recorded personal files; --keep-models overrides model removal. Shared model directories and unrecorded or external models remain.

GNOME custom shortcuts require manual removal in Keyboard Settings. On unmanaged installs, niri and Sway shortcuts also require manual removal from your compositor config. Managed installs record those edits for removal.

Modified integrations and customized services are preserved. Remove reported bar references before retrying integration removal. Customized services retain their runtime and launcher until reconciled. Receipts remain for cleanup retries.

--remove-permissions removes only recorded group memberships or rules that installation added. --skip-permissions preserves them. Recognized pre-existing udev rules are not treated as installation-owned.

Before merging a change that expands the Python range, every CLI/backend plan must install, pass pip check, and import successfully at its advertised ceiling. ONNX and faster-whisper variants currently run on 3.14; all other plans run on 3.15. Remove either exception only after all its variants pass on 3.15. Run the dependency-smoke helper in disposable containers, or the Python dependency smoke workflow when it is already available on the default branch. Retain the candidate revision or source fingerprint, logs and package versions. Investigate failures before claiming support; do not skip failing backends. Validate before merging. Dependency-plan installation already restores the old venv when installation fails; managed updates also preserve the active generation. The compatibility guard avoids attempting known unsupported installations.

For releases, use the existing tag flow from a clean, committed checkout:

Terminal window
./bump-version.sh MAJOR.MINOR.PATCH

The script checks tools, GitHub authentication, payload validity, and publication of every required CUDA/Vulkan wheel with a valid checksum entry before pushing the tag. If wheels are missing, finish Build PyWhisperCPP Wheels and rerun. Adding new Python-tagged filenames alone does not require a wheel build-number bump; published wheel contents are never overwritten.

After pushing the tag, the script waits for Application release and triggers Python dependency smoke against that same tag and commit. Both must pass before it updates local AUR metadata. Both workflows must be active on the default branch before the first automated bump. Dependency coverage remains ceiling-only; it checks installation and imports, not GPU execution, native sidecars, model loading, microphone capture or transcription accuracy.

Rerun the same command from the tagged commit to resume. Existing tags must match HEAD and are never moved; active or successful matching checks are reused, and failed/cancelled checks are rerun once per invocation. Discovery waits up to two minutes and completion up to three hours. A timeout leaves remote runs active. Failures print run links; inspect them and resolve the problem before retrying. If the tagged source needs a code fix, use a new release version.

Review and publish the draft manually, then review and commit/push AUR changes. Include the concrete release tag in the Python-upgrade recovery command in the release notes. Direct tag pushes bypass the script’s extra checks, and the application workflow can prepare a draft before dependency smoke finishes.

The website installer installs the latest published release. An old git-clone install that reruns it is migrated.

HYPRWHSPR_LEGACY_BOOTSTRAP=1 keeps the old clone install for one more release. --version, --python, --repair and existing release installs ignore it.

Container smoke tests and mocked tests do not validate live Wayland/X11 service behavior. Before a release, test install, CPU/GPU selection, update, interrupted recovery, interpreter replacement, migration and uninstall in a desktop VM.

Release archives and recovery helpers use HTTPS and SHA-256 checksums. Extraction rejects unsafe archives. Checksums verify publisher-asset consistency, not an independent signature. Backend-wheel and GUI-runtime releases are excluded.

  1. Push the version tag (vMAJOR.MINOR.PATCH). The application release workflow builds the payload, verifies checksums, and runs the distro smoke tests.
  2. Wait for the entire workflow to succeed. It attaches the tested assets to a draft release and links the draft in the workflow summary.
  3. Review the assets and edit the generated release notes before publishing.
  4. Publish the draft manually on GitHub. Automation never publishes application releases; release subscribers see the notes you prepared at publication.

Rerunning the workflow refreshes assets on an existing draft without changing its title or notes. An already published release is left untouched. Do not publish while a workflow run is still uploading assets.

Managed installs and updates ignore drafts and continue selecting the previous compatible published release until you publish the new one. Tag source archives are available independently of the draft, so defer publishing the AUR update until the application release is ready. Backend-wheel and GTK runtime release workflows are unchanged.