Hermes Agent install or update failed

What you see

The install one-liner stops with an error; the install finishes but your shell says hermes: command not found; you get an unsupported Python or uv: command not found message; or hermes update completes but the bot still behaves like the old version, settings seem missing, or git reports a dirty tree.

Likely causes

Most install problems are environmental rather than bugs in Hermes: the launcher exists but your shell can't see it, a prerequisite is missing, or an earlier install left a conflicting copy behind. Update problems usually come from running the wrong update path for your install type, or from a long-running gateway that is still executing the old code after the files on disk changed.

• Your shell hasn't reloaded PATH after install (the CLI lives in ~/.local/bin on Linux, macOS and WSL2).
• The installer was run with sudo, or an old sudo install left /usr/local/bin/hermes behind.
• Missing prerequisites: the POSIX source installer needs git, curl, tar and SHA-256 tools; minimal Linux images may lack libatomic for Node.js.
• You are on Docker, Desktop, Termux or Nix, where hermes update is the wrong tool.
• A gateway kept running old code, or new config options haven't been migrated.

Check this first

• which hermes and ls ~/.local/bin/hermes: is the launcher there?
• hermes doctor: diagnoses config and dependency problems and tells you which update method applies to your install.
• Look at the install log under logs/install.log in your Hermes data directory, or rerun the installer with --verbose (or HERMES_INSTALL_VERBOSE=1) to stream everything.
• hermes update --check: is the checkout actually behind?
• tail -f ~/.hermes/logs/update.log: the update's own log, which survives terminal disconnects.
• hermes gateway status after an update.

Fix

Match the fix to the symptom:

• command not found: run source ~/.bashrc or source ~/.zshrc, or open a new terminal. If your shell config is unusual, add export PATH="$HOME/.local/bin:$PATH" yourself.
• Permission denied during install: don't use sudo with the installer. If you installed with sudo before, remove /usr/local/bin/hermes and rerun the standard installer.
• Python version errors: current first-party installs use a pinned Python the installer provides (3.14). Don't swap interpreters inside an installed app or container; rerun the installer or hermes doctor instead.
• uv: command not found: install uv with its official script, then reload your shell.
• Browser or computer-use downloads failed: the installer prints a retry command; you can also restore them later with hermes pm install agent-browser or hermes pm install cua-driver.
• Missing config after update: run hermes config check, then hermes config migrate.
• Bot still on old code: hermes gateway restart, or rerun hermes update, which retries interrupted restarts.
• Docker installs: docker pull the new image and recreate the container with the same data mount instead of running hermes update.

If it still fails

If an update left you in a worse state, check git status --short to see whether local edits were reapplied, and git stash list for edits that were parked. Local commits on main are saved under refs/hermes-update-backups/. To roll back to an older release after the new gateway has written state.db, stop the gateway, check out the older release and restore a pre-update snapshot or a backup with hermes import. When asking for help, hermes dump prints a copy-pasteable setup summary, and the project's GitHub issues are the place to report installer bugs.

Related guides

• How to update Hermes Agent safely
• Hermes Agent terminal can't find files or programs
• Where Hermes Agent runs: host vs work environment

Spotted something wrong or out of date? Tell us on X at @HermesWatcher↗ (opens in a new tab) and we will fix it.

New Hermes Agent updates every day on X. Follow @HermesWatcher