Install Issues

You may encounter various environment issues when installing Hermes Agent. This page covers the most common installation failures and their solutions.

Python Version Incompatibility

Symptom: SyntaxError or Python version not supported during installation.

Cause: Hermes Agent requires Python 3.10 or higher.

Solutions:

# Check current Python version
python3 --version

# If version is below 3.10, upgrade needed

Upgrade Python on Ubuntu / Debian

sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update
sudo apt install python3.11 python3.11-venv python3.11-dev

# Set as default version
sudo update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.11 1

Upgrade Python on macOS

brew install [email protected]

Use uv to Manage Python

# uv automatically installs the correct Python version
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

Tip

We recommend Python 3.11+, which is the most thoroughly tested version for Hermes Agent.

Dependency Conflicts

Symptom: Dependency version conflict errors during pip install.

Cause: Packages already installed in system Python environment are incompatible with Hermes Agent dependencies.

Solutions:

# Method 1: Use virtual environment (recommended)
python3 -m venv ~/.hermes-venv
source ~/.hermes-venv/bin/activate
pip install hermes-agent

# Method 2: Use one-line install script (auto-handles virtual environment)
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

# Method 3: Force reinstall
pip install --force-reinstall hermes-agent

# Method 4: Use uv instead of pip (faster dependency resolution)
pip install uv
uv pip install hermes-agent

Permission Denied

Symptom: Permission denied or [Errno 13] during installation.

Cause: Attempting to install to system-level Python directory without sufficient permissions.

Solutions:

# ❌ Do NOT use sudo to install
# sudo pip install hermes-agent

# ✅ Method 1: Use --user flag
pip install --user hermes-agent

# ✅ Method 2: Use virtual environment
python3 -m venv myenv
source myenv/bin/activate
pip install hermes-agent

# ✅ Method 3: Fix ~/.hermes directory permissions
sudo chown -R $(whoami):$(whoami) ~/.hermes

Caution

Never use sudo pip install. This installs packages to system directories and may cause issues with other programs. If you previously installed with sudo, uninstall first:

sudo pip uninstall hermes-agent

Network Timeout or Download Failure

Symptom: Cannot download packages or connection timeout during installation.

Cause: Network issues, especially accessing PyPI from mainland China may be slow.

Solutions:

# Method 1: Use domestic mirror (China users)
pip install hermes-agent -i https://pypi.tuna.tsinghua.edu.cn/simple

# Method 2: Use Hermes China mirror install script
curl -fsSL https://res1.hermesagent.org.cn/install.sh | bash

# Method 3: Set pip to permanently use mirror
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

# Method 4: Set proxy
export HTTPS_PROXY=http://127.0.0.1:7890
pip install hermes-agent

Git Clone Failure

Symptom: git clone timeout or connection refused.

Cause: GitHub access restricted.

Solutions:

# Method 1: Use GitHub mirror
git clone https://ghproxy.com/https://github.com/NousResearch/hermes-agent.git

# Method 2: Configure Git proxy
git config --global http.proxy http://127.0.0.1:7890
git config --global https.proxy http://127.0.0.1:7890

# Method 3: Download zip directly
wget https://github.com/NousResearch/hermes-agent/archive/refs/heads/main.zip
unzip main.zip
cd hermes-agent-main
pip install -e .

WSL2 Specific Issues

Symptom: Special errors when installing in WSL2.

Common Issues and Solutions:

# Issue 1: Missing build tools in WSL2
sudo apt update && sudo apt install -y build-essential python3-dev

# Issue 2: Poor filesystem performance (cross Windows/Linux)
# Don't install under /mnt/c/, use native Linux filesystem instead
cd ~
git clone https://github.com/NousResearch/hermes-agent.git

# Issue 3: DNS resolution failure
echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf

Docker Installation Issues

Symptom: Docker pull image fails.

Solutions:

# Method 1: Use domestic Docker mirror (China users)
docker pull registry.cn-hangzhou.aliyuncs.com/nousresearch/hermes-agent:latest

# Method 2: Configure Docker proxy
mkdir -p /etc/systemd/system/docker.service.d
cat > /etc/systemd/system/docker.service.d/proxy.conf << EOF
[Service]
Environment="HTTPS_PROXY=http://127.0.0.1:7890"
EOF
sudo systemctl daemon-reload
sudo systemctl restart docker

# Method 3: Manual import
# Export image on machine with network access
docker save nousresearch/hermes-agent:latest -o hermes-agent.tar
# Transfer to target machine and import
docker load -i hermes-agent.tar

uv Installation Failure

Symptom: uv installation fails in one-line install script.

Solutions:

# Manually install uv
curl -fsSL https://astral.sh/uv/install.sh | sh

# Or install via pip
pip install uv

# Then re-run Hermes install script
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

Post-Installation Verification

After installation, run these commands to verify everything is working:

hermes --version    # Confirm version number
hermes doctor       # Comprehensive diagnosis

If hermes doctor shows all ✅, installation is successful.

Complete Reinstall Process

If none of the above solutions work, try a complete reinstall:

# 1. Backup important data
cp -r ~/.hermes ~/.hermes.backup

# 2. Remove old installation
pip uninstall hermes-agent
rm -rf ~/.hermes-agent
rm -rf ~/.hermes-venv

# 3. Reinstall
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

# 4. Restore data
cp -r ~/.hermes.backup/memory ~/.hermes/
cp -r ~/.hermes.backup/skills ~/.hermes/

Related Pages

• Common Errors — Common runtime errors
• Model Issues — LLM configuration issues
• hermes doctor — Automatic diagnostic tool
• Linux Installation — Detailed Linux installation guide