---
title: "How to uninstall Hermes Agent cleanly (Linux, Windows, and Mac)"
description: "Remove Hermes Agent from macOS, Linux, or Windows, including the CLI, repo, virtualenv, state directory, gateway service, Desktop app, and optional Playwright caches."
author: "Carlos García"
published: 2026-07-23
updated: 2026-07-23
language: en
human_url: "https://kiia.cloud/blog/uninstall-hermes-agent/"
---

> **In 60 seconds:** if the CLI still works, run `hermes uninstall` and choose whether to keep `~/.hermes/` for a future reinstall. Then remove any remaining binary and repo with `rm -f ~/.local/bin/hermes` and `rm -rf ~/.hermes/hermes-agent`. If the gateway runs as a managed service, stop it with `hermes gateway stop`, then disable it with `systemctl --user disable hermes-gateway` on Linux, `launchctl remove ai.hermes.gateway` on macOS, or `schtasks /Delete /F /TN "Hermes Gateway"` on Windows. A full reset, including the virtualenv and Playwright caches, uses `rm -rf ~/.hermes ~/.cache/ms-playwright`.

[Hermes Agent](https://hermes-agent.nousresearch.com) stores components in several filesystem locations. A partial uninstall can leave behind its binary, repo, virtualenv, state, or gateway service. This guide covers the official uninstaller, a manual cleanup, and the service-only path for an orphaned gateway.

## Before uninstalling: stop everything

Before running the uninstaller, **close anything that might have open handles** on the binary or venv:

- Close any open `hermes` REPL in other terminals.
- Exit Hermes Desktop if you're using it (Windows / macOS).
- Stop the gateway: `hermes gateway stop`.

> On Windows, `hermes.exe` stays locked while Hermes Desktop, the gateway, or a Python REPL is using it. Deleting the virtualenv or binary before those processes stop can produce an "access denied" error or a failed rename.

## Path 1: use `hermes uninstall`

If `hermes --version` responds, this is the recommended path. The uninstaller automatically detects whether you installed in per-user mode or root-mode and cleans what corresponds.

```bash
hermes uninstall
```

At the end of the process, the uninstaller asks:

> Keep `~/.hermes/` (config, auth, sessions, skills) for a future reinstall? [Y/n]

- **Y** (recommended default): keeps `~/.hermes/`, which saves you from reconfiguring provider keys, channels, and other settings after a reinstall.
- **n**: removes `~/.hermes/` entirely, so you start from scratch next time.

After running the uninstaller, **you still have the binary at `~/.local/bin/hermes` and the repo checkout at `~/.hermes/hermes-agent/`**. The uninstaller removes them in some cases; if they remain, manual is:

```bash
rm -f ~/.local/bin/hermes           # binary symlink
rm -rf ~/.hermes/hermes-agent       # repo checkout
# Optional: remove the venv
rm -rf ~/.hermes/venvs
```

If you installed in **root-mode** (sudo):

```bash
sudo rm -f /usr/local/bin/hermes
sudo rm -rf /usr/local/lib/hermes-agent
```

## Path 2: remove each component manually

If you prefer to understand each step (servers with audit, custom setups, container cleanup), this is the order.

### Step 1: stop the gateway

```bash
hermes gateway stop
```

If it was registered as a managed service:

```bash
# Linux
systemctl --user disable hermes-gateway

# macOS
launchctl remove ai.hermes.gateway

# Windows (PowerShell)
schtasks /Delete /F /TN "Hermes Gateway"
```

### Step 2: remove the binary

Per-user (default):

```bash
rm -f ~/.local/bin/hermes
```

Root-mode:

```bash
sudo rm -f /usr/local/bin/hermes
```

### Step 3: remove the repo

Per-user:

```bash
rm -rf ~/.hermes/hermes-agent
```

Root-mode:

```bash
sudo rm -rf /usr/local/lib/hermes-agent
```

### Step 4: optionally remove the virtualenv

```bash
# Per-user
rm -rf ~/.hermes/venvs

# Root-mode
sudo rm -rf /usr/local/lib/hermes-agent/venv
```

### Step 5: optionally remove config, auth, sessions, and skills

If you decided not to keep `~/.hermes/`:

```bash
# Linux / macOS
rm -rf ~/.hermes

# Windows (PowerShell)
Remove-Item -Recurse -Force "$env:USERPROFILE\.hermes"
```

### Step 6: optionally remove Playwright caches

Chromium stays cached at `~/.cache/ms-playwright/` (Linux/macOS) or `%LOCALAPPDATA%\ms-playwright\` (Windows). They weigh ~150-300 MB. If you're not going to reinstall Hermes soon or want to free up space:

```bash
# Linux / macOS
rm -rf ~/.cache/ms-playwright

# Windows (PowerShell)
Remove-Item -Recurse -Force "$env:LOCALAPPDATA\ms-playwright"
```

## Path 3: remove an orphaned service

If you installed without `curl | bash` (for example cloning the repo and setting up a systemd unit manually), or if the CLI is no longer available but the service is still running:

### Stop and disable the service

```bash
# Linux
systemctl --user stop hermes-gateway
systemctl --user disable hermes-gateway

# macOS
launchctl unload ~/Library/LaunchAgents/ai.hermes.gateway.plist   # if you have the plist
launchctl remove ai.hermes.gateway

# Windows (PowerShell)
schtasks /Delete /F /TN "Hermes Gateway"
```

### Remove the binary and files

```bash
rm -f ~/.local/bin/hermes
rm -rf /path/to/hermes-agent        # the path where you cloned it
```

And if you configured a custom `HERMES_HOME`:

```bash
unset HERMES_HOME
rm -rf /path/to/your/hermes/home
```

## If you installed via Docker or NixOS

**Docker:** delete the image and the containers.

```bash
docker ps -a | grep hermes         # list containers
docker rm -f hermes-gateway        # remove container (adjust the name)
docker images | grep hermes        # list images
docker rmi hermes-agent:latest     # remove image
```

**NixOS / Nix profile:** Nix installations are immutable and managed by generations.

```bash
nix profile list | grep hermes     # see what generations exist
nix profile remove hermes-agent    # remove
# Optional: clean old generations
nix-collect-garbage -d
```

For setups with the NixOS module, remove the module from your `configuration.nix` and rebuild.

## If you installed as a service user without sudo

If you followed the recommended pattern of [install without sudo](https://hermes-agent.nousresearch.com/docs/getting-started/installation#non-sudo--system-service-user-installs), the service user has `~/.local/bin/hermes` and `~/.hermes/`. The uninstall is the same as per-user mode, but watch out for the admin:

- The admin who ran `sudo npx playwright install-deps chromium` can remove those system libraries with `apt remove` (they're standard Chromium libraries), but **won't** affect other users who don't need them.
- If you created a system-wide symlink (`sudo ln -s /home/hermes/.hermes/hermes-agent/venv/bin/hermes /usr/local/bin/hermes`), remember to remove it:

```bash
sudo rm -f /usr/local/bin/hermes
```

## Post-uninstall verification

After uninstalling, verify nothing remains:

```bash
# macOS / Linux
which hermes                           # should return nothing
launchctl list | grep hermes           # should list nothing
systemctl --user list-units --type=service | grep hermes   # should list nothing
ls -la ~/.hermes 2>/dev/null           # No such file or directory (if you removed config)

# Windows (PowerShell)
Get-Command hermes -ErrorAction SilentlyContinue
Get-ScheduledTask | Where-Object {$_.TaskName -like "*Hermes*"}
Test-Path "$env:USERPROFILE\.hermes"   # False if you removed config
```

If everything returns empty / False, the uninstall is complete.

## Reinstalling later

If you plan to reinstall (for example upgrade to a new version), you can keep `~/.hermes/`:

```bash
# Stop daemon, keep everything else
hermes gateway stop
hermes uninstall         # answer "Y" to "keep ~/.hermes/"
```

After reinstalling, the preserved config and skills are already in place. Run `hermes doctor` to verify the installation.

Before deleting `~/.hermes/`, make a copy if it contains custom skills, provider configuration, or sessions you may need later. The other removal steps can be repeated; that state directory is the part you cannot recover after deletion.

## Frequently asked questions

### What's the quick command to uninstall Hermes Agent?

If the CLI is still available, run `hermes uninstall`. It asks at the end whether you want to keep `~/.hermes/` (config) for future reinstall or remove it entirely. Then remove the binary and repo manually (see below).

### How do I uninstall if I installed as root or with sudo?

The uninstaller detects the install mode (per-user or root). In root-mode, the paths are `/usr/local/lib/hermes-agent/`, `/usr/local/bin/hermes`, and `/root/.hermes/`. `hermes uninstall` cleans those up; afterwards `sudo rm -rf` if anything remains.

### What if the gateway is still running as a managed service?

Stop it first: `hermes gateway stop`. Then on Linux: `systemctl --user disable hermes-gateway`. On macOS: `launchctl remove ai.hermes.gateway`. On Windows: `schtasks /Delete /F /TN "Hermes Gateway"` (or whatever name you used).

### What happens to my config (`~/.hermes/`) and the virtualenv?

The uninstaller asks at the end if you want to keep `~/.hermes/`. If you say "keep", everything stays (config, auth.json, sessions, skills) and you can reinstall without reconfiguring. If you say "remove", it deletes it all and you start from scratch.

### How do I remove the repo and the venv?

Manual: `rm -f ~/.local/bin/hermes` (removes the binary symlink), `rm -rf ~/.hermes/hermes-agent` (deletes the repo checkout), and `rm -rf ~/.hermes/venvs` (deletes the virtualenvs). If you installed in root-mode: `sudo rm -f /usr/local/bin/hermes && sudo rm -rf /usr/local/lib/hermes-agent`.

### What about the Playwright/Chromium caches?

They remain at `~/.cache/ms-playwright/` (Linux/macOS) or `%LOCALAPPDATA%\ms-playwright\` (Windows). `hermes uninstall` doesn't touch them by default because they're useful if you're going to reinstall and want to avoid the re-download. To remove them: `rm -rf ~/.cache/ms-playwright`.

## Step-by-step guide

### Uninstall Hermes Agent on Linux, Windows, or macOS

Uninstall the Hermes Agent AI agent cleanly: gateway as a service, state dir, virtualenv, repo, CLI, and optionally the Playwright caches.

**Total time:** PT3M

**Tools:** macOS / Linux / WSL2 / Windows 10+ native, Hermes Agent CLI (`hermes`)

### 1. Stop the gateway and any open processes

Before uninstalling, close any open `hermes` REPL in other terminals and stop the gateway: `hermes gateway stop`. On Windows also exit Hermes Desktop if you're using it. This prevents handles from remaining open on the binary or venv that would block the uninstall.

### 2. Disable the managed service (if you created one)

On Linux: `systemctl --user disable hermes-gateway`. On macOS: `launchctl remove ai.hermes.gateway`. On Windows (PowerShell): `schtasks /Delete /F /TN "Hermes Gateway"`. If you installed Hermes Desktop on Windows, also exit the tray app.

### 3. Run the official uninstaller

Execute `hermes uninstall`. The uninstaller detects the install mode (per-user or root) and asks at the end whether you want to keep `~/.hermes/` (recommended if you plan to reinstall) or delete it completely. To force the non-interactive version, you can answer `yes` to everything and delete the directory manually afterwards.

### 4. Remove the binary and repo (manual)

Per-user: `rm -f ~/.local/bin/hermes` (symlink) and `rm -rf ~/.hermes/hermes-agent` (repo checkout). Root-mode: `sudo rm -f /usr/local/bin/hermes` and `sudo rm -rf /usr/local/lib/hermes-agent`. If you also want to remove the venv: `rm -rf ~/.hermes/venvs`.

### 5. (Optional) Remove config and caches

If you decided to keep `~/.hermes/` during the uninstaller but now want to reset: `rm -rf ~/.hermes` (Linux/macOS) or `Remove-Item -Recurse -Force $env:USERPROFILE\.hermes` (Windows). For Playwright caches: `rm -rf ~/.cache/ms-playwright` or `Remove-Item -Recurse -Force $env:LOCALAPPDATA\ms-playwright`.

### 6. Verify the uninstall

`which hermes` should return nothing. `hermes doctor` should report "command not found" (you don't have to run it, it's just a sanity check). `ls ~/.hermes/` and `ls /usr/local/lib/` confirm there are no leftovers.