Managed installations
Verified releases for Debian/Ubuntu, Fedora and openSUSE. AUR updates stay with your package manager; development checkouts keep their existing workflow.
Commands
Section titled “Commands”hyprwhspr updatehyprwhspr update --version v1.2.3hyprwhspr install statushyprwhspr install repairhyprwhspr install repair --python /absolute/path/to/pythonhyprwhspr uninstallhyprwhspr uninstall --purgehyprwhspr uninstall --purge --keep-modelsUpdates 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 and storage
Section titled “Python and storage”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.
Recovery
Section titled “Recovery”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.
After a distro Python upgrade
Section titled “After a distro Python upgrade”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:
# 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/python3Replace 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 and removal
Section titled “Migration and removal”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.
Release rollout
Section titled “Release rollout”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:
./bump-version.sh MAJOR.MINOR.PATCHThe 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.
Publishing an application release
Section titled “Publishing an application release”- Push the version tag (
vMAJOR.MINOR.PATCH). The application release workflow builds the payload, verifies checksums, and runs the distro smoke tests. - Wait for the entire workflow to succeed. It attaches the tested assets to a draft release and links the draft in the workflow summary.
- Review the assets and edit the generated release notes before publishing.
- 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.