# Hermes Agent install or update failed > Symptom-led fixes for a Hermes install script that errors out, a missing hermes command, Python or permission problems, and updates that leave things half-done. Canonical: https://hermeswatcher.com/troubleshoot/install-or-update-failed Section: Troubleshooting ยท Getting started Last reviewed: Oct 20, 2026 Basis: Explained from the official Hermes Agent docs and repository (Nous Research). Steps follow the linked official sources. ## 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](https://hermeswatcher.com/learn/updating-hermes-safely.md) - [Hermes Agent terminal can't find files or programs](https://hermeswatcher.com/troubleshoot/terminal-cannot-find-files-or-programs.md) - [Where Hermes Agent runs: host vs work environment](https://hermeswatcher.com/learn/where-hermes-runs.md) ## Related tools - [CLI: run bounded tasks and inspect the working environment](https://hermeswatcher.com/tools/cli.md) - [Deployment: separate the agent host from its execution sandbox](https://hermeswatcher.com/tools/deployment.md) - [Desktop: manage conversations and inspect artifacts visually](https://hermeswatcher.com/tools/desktop.md) ## Sources - [Installation (official docs)](https://hermes-agent.nousresearch.com/docs/getting-started/installation/) - [Updating and Uninstalling (official docs)](https://hermes-agent.nousresearch.com/docs/getting-started/updating) - [FAQ and Troubleshooting (official docs)](https://hermes-agent.nousresearch.com/docs/reference/faq) - [NousResearch/hermes-agent on GitHub](https://github.com/NousResearch/hermes-agent) --- HermesWatcher is an independent guide. It is not affiliated with or endorsed by Nous Research. The [official Hermes Agent documentation](https://hermes-agent.nousresearch.com/docs) and [repository](https://github.com/NousResearch/hermes-agent) from Nous Research are the authority; each page here lists the official sources it was written from. If this site and the official docs disagree, trust the official docs. Index for agents: https://hermeswatcher.com/llms.txt