Installing Hermes Agent 0.21.3 on CentOS 7: Fixing Python Version Conflicts, Dependency Resolution Errors, and Pillow Build Failures

Installing modern AI tooling on an older enterprise Linux environment often reveals problems that never appear on a fresh workstation.

While setting up Hermes Agent 0.21.3 on a long-running CentOS 7 machine used for EDA workloads, I encountered several unrelated issues in sequence:

Hermes launching with the wrong Python interpreter
Missing core dependencies after installation
Dependency resolution conflicts involving pillow-heif
Pillow 12.3.0 source build failures on CentOS 7
Environment contamination from EDA-specific LD_LIBRARY_PATH settings

After resolving each issue, Hermes Agent started successfully with a fully functional installation, including the OpenAI SDK.

This article documents the entire troubleshooting process and provides a reproducible installation path.

The First Error: `future feature annotations is not defined`

The initial attempt was simply to check the Hermes version.

env -u LD_LIBRARY_PATH \
  "$HOME/.hermes/hermes-agent/hermes" --version

The result was an immediate crash.

Traceback (most recent call last):
  File "/home/EDA/.hermes/hermes-agent/hermes", line 10, in <module>
    from hermes_cli.main import main
  File "/home/EDA/.hermes/hermes-agent/hermes_cli/main.py", line 16, in <module>
    import hermes_bootstrap
  File "/home/EDA/.hermes/hermes-agent/hermes_bootstrap.py", line 16
    from __future__ import annotations
SyntaxError: future feature annotations is not defined

At first glance, this looks like a code problem.

In reality, it usually indicates that the application is running under an older Python interpreter.

Checking the Hermes launcher confirmed that it relies on whatever python3 appears in the environment.

head -n 3 "$HOME/.hermes/hermes-agent/hermes"

Output:

#!/usr/bin/env python3
"""
Hermes Agent CLI launcher.

Next, I verified the Python version inside the virtual environment.

env -u LD_LIBRARY_PATH \
  "$HOME/.hermes/hermes-agent/venv/bin/python" --version

Output:

Python 3.11.16

Launching Hermes explicitly with that interpreter immediately worked.

env -u LD_LIBRARY_PATH \
  "$HOME/.hermes/hermes-agent/venv/bin/python" \
  "$HOME/.hermes/hermes-agent/hermes" --version

Result:

Hermes Agent v0.21.3 (2026.9.14)
Python: 3.11.16
OpenAI SDK: Not installed

At this stage, the root cause was clear.

Hermes itself was fine. The system environment was invoking the wrong Python runtime.

Discovering That Core Dependencies Were Missing

Although Hermes could now start, the version output revealed another problem.

OpenAI SDK: Not installed

Inspecting the virtual environment showed that almost nothing had been installed.

env -u LD_LIBRARY_PATH \
  "$HOME/.local/bin/uv" pip list \
  --python "$HOME/.hermes/hermes-agent/venv/bin/python"

Output:

Package     Version
----------- -------
pillow      12.2.0
pillow-heif 0.18.0

The OpenAI SDK and most Hermes dependencies were absent.

Looking into the project configuration confirmed that openai was declared as a required dependency.

grep -nE '^\[project\]|^dependencies =|pillow-heif|openai' \
  "$HOME/.hermes/hermes-agent/pyproject.toml"

Relevant section:

dependencies = [
  ...
  "openai==2.24.0",
  ...
]

The environment clearly did not match the project’s dependency definition.

A Failed Installation Caused by Dependency Constraints

To keep Pillow pinned to a known working version, I initially created a constraints file.

cat > /tmp/hermes-constraints.txt <<'EOF'
pillow==12.2.0
pillow-heif==0.18.0
EOF

Installation immediately failed.

uv pip install \
  --python "$HOME/.hermes/hermes-agent/venv/bin/python" \
  -c /tmp/hermes-constraints.txt \
  -e "$HOME/.hermes/hermes-agent"

Error:

Because hermes-agent==0.21.3 depends on pillow-heif>=1.4.0,<2
and pillow-heif==0.18.0

requirements are unsatisfiable

The dependency resolver was correct.

My constraints file demanded:

pillow-heif==0.18.0

The project metadata required:

pillow-heif>=1.4.0,<2

Those requirements cannot coexist.

No resolver can produce a valid solution from contradictory constraints.

Dry Run Revealed the Real Problem: Pillow 12.3.0

After removing the constraints file, I performed a dry run.

uv pip install \
  --python "$HOME/.hermes/hermes-agent/venv/bin/python" \
  -e . \
  --dry-run

One line immediately stood out.

- pillow==12.2.0
+ pillow==12.3.0

The installer was preparing to upgrade Pillow.

Searching the project configuration exposed the reason.

grep -n "12.3.0" pyproject.toml

Output:

"Pillow==12.3.0",

Earlier edits had only modified lowercase references to pillow.

The actual dependency definition still contained a hard pin to Pillow 12.3.0.

That version was driving every subsequent installation attempt.

Pillow 12.3.0 Failed to Build on CentOS 7

Proceeding with installation triggered a source build.

The critical error appeared during compilation.

src/libImaging/Mode.c:30:5:
error: 'for' loop initial declarations are only allowed in C99 mode

The compiler pointed to code similar to:

for (size_t i = 0; i < ...; i++) {

It also suggested:

use -std=c99 or -std=gnu99

At this point, the issue was straightforward.

Pillow 12.3.0 was not installing from a prebuilt wheel and had fallen back to source compilation.

The CentOS 7 toolchain on this machine could not satisfy the build requirements.

Continuing to fight compiler settings would have been far more work than simply using the already verified Pillow 12.2.0 release.

Pinning Pillow 12.2.0 in pyproject.toml

I located the Pillow declarations.

grep -nE '^[[:space:]]*"?[Pp]illow' pyproject.toml

The relevant section became:

"Pillow==12.2.0",
"pillow-heif==0.18.0",

Running another dry run produced a much cleaner result.

uv pip install \
  --python "$HOME/.hermes/hermes-agent/venv/bin/python" \
  -e . \
  --dry-run

Output:

Resolved 64 packages
Would install 62 packages

The attempted Pillow upgrade had disappeared.

Dependency resolution was finally stable.

Successful Installation

With the dependency definitions corrected, installation completed normally.

uv pip install \
  --python "$HOME/.hermes/hermes-agent/venv/bin/python" \
  -e "$HOME/.hermes/hermes-agent"

Result:

Installed 62 packages

Among the installed packages were:

openai==2.24.0
httpx==0.28.1
fastapi==0.141.1
rich==14.3.3
pydantic==2.13.4

The core Hermes stack was finally present.

Verifying OpenAI, Pillow, and pillow-heif

Before testing Hermes itself, I verified the three packages that had caused most of the installation friction.

env -u LD_LIBRARY_PATH \
"$HOME/.hermes/hermes-agent/venv/bin/python" -c '
import openai, PIL, pillow_heif
print("openai:", openai.__version__)
print("Pillow:", PIL.__version__)
print("pillow-heif:", pillow_heif.__version__)
'

Output:

openai: 2.24.0
Pillow: 12.2.0
pillow-heif: 0.18.0

Everything imported successfully.

Verifying the Hermes CLI

Checking the version now produced the expected output.

env -u LD_LIBRARY_PATH \
"$HOME/.hermes/hermes-agent/venv/bin/python" \
"$HOME/.hermes/hermes-agent/hermes" --version

Output:

Hermes Agent v0.21.3 (2026.9.14)
Install method: git
Python: 3.11.16
OpenAI SDK: 2.24.0

Running the help command also worked correctly.

env -u LD_LIBRARY_PATH \
"$HOME/.hermes/hermes-agent/venv/bin/python" \
"$HOME/.hermes/hermes-agent/hermes" --help

Available commands included:

chat
setup
doctor
dashboard
gateway
sessions
memory
plugins
update

At this point the installation could be considered fully functional.

Making `hermes` Available as a Direct Command

The most reliable launch command remained:

env -u LD_LIBRARY_PATH \
"$HOME/.hermes/hermes-agent/venv/bin/python" \
"$HOME/.hermes/hermes-agent/hermes"

Typing that every time quickly becomes tedious.

A lightweight wrapper script solves the problem.

Create a personal executable directory:

mkdir -p "$HOME/bin"

Create the wrapper:

cat > "$HOME/bin/hermes" <<'EOF'
#!/bin/bash
exec env -u LD_LIBRARY_PATH \
  "$HOME/.hermes/hermes-agent/venv/bin/python" \
  "$HOME/.hermes/hermes-agent/hermes" "$@"
EOF

chmod +x "$HOME/bin/hermes"

Add the directory to your shell path:

echo 'export PATH="$HOME/bin:$PATH"' >> "$HOME/.bashrc"
source "$HOME/.bashrc"

Verify the result:

which hermes

Expected output:

/home/EDA/bin/hermes

From that point forward, Hermes can be launched directly.

hermes

Or:

hermes setup

The wrapper automatically selects the correct Python environment and strips problematic EDA library settings.

Quick Reference Checklist

Confirm that Hermes uses Python 3.11.
Launch Hermes directly through the virtual environment interpreter.
Verify installed packages with uv pip list.
Inspect pyproject.toml for the actual Pillow dependency definition.
Replace Pillow==12.3.0 with Pillow==12.2.0.
Keep pillow-heif==0.18.0.
Reinstall using uv pip install -e ..
Verify imports for OpenAI, Pillow, and pillow-heif.
Create a wrapper script that removes LD_LIBRARY_PATH.
Add the wrapper location to PATH.

FAQ

Why did Hermes report `future feature annotations is not defined`?

The launcher was executing under an older Python interpreter instead of Python 3.11 from the virtual environment.

Why did Hermes show `OpenAI SDK: Not installed`?

The virtual environment contained only Pillow-related packages. Most project dependencies had never been installed successfully.

Why did dependency resolution fail?

The constraints file pinned pillow-heif==0.18.0 while the project metadata required a different version range. The requirements were mutually incompatible.

Why did installation keep upgrading Pillow?

The project configuration still contained:

"Pillow==12.3.0"

The dependency resolver followed that definition.

Why did Pillow 12.3.0 fail on CentOS 7?

Installation fell back to source compilation, and the available compiler environment could not satisfy the build requirements.

How can I confirm that Hermes is installed correctly?

Run:

hermes --version

A successful installation should report:

OpenAI SDK: 2.24.0

along with the Hermes version information.

Why remove `LD_LIBRARY_PATH` when launching Hermes?

The EDA environment injects library paths that can interfere with Hermes and its Python runtime.

What is the recommended way to start Hermes afterward?

Use the wrapper command:

hermes

The wrapper automatically selects the correct virtual environment and avoids environment-related conflicts.

CentOS 7 AI Setup Guide: Fixing Hermes Agent Python & Pillow Errors

Installing Hermes Agent 0.21.3 on CentOS 7: Fixing Python Version Conflicts, Dependency Resolution Errors, and Pillow Build Failures

The First Error: future feature annotations is not defined

Discovering That Core Dependencies Were Missing

A Failed Installation Caused by Dependency Constraints

Dry Run Revealed the Real Problem: Pillow 12.3.0

Pillow 12.3.0 Failed to Build on CentOS 7

Pinning Pillow 12.2.0 in pyproject.toml

Successful Installation

Verifying OpenAI, Pillow, and pillow-heif

Verifying the Hermes CLI

Making hermes Available as a Direct Command

Quick Reference Checklist

FAQ

Why did Hermes report future feature annotations is not defined?

Why did Hermes show OpenAI SDK: Not installed?

Why did dependency resolution fail?

Why did installation keep upgrading Pillow?

Why did Pillow 12.3.0 fail on CentOS 7?

How can I confirm that Hermes is installed correctly?

Why remove LD_LIBRARY_PATH when launching Hermes?

What is the recommended way to start Hermes afterward?

Related Posts

The First Error: `future feature annotations is not defined`

Making `hermes` Available as a Direct Command

Why did Hermes report `future feature annotations is not defined`?

Why did Hermes show `OpenAI SDK: Not installed`?

Why remove `LD_LIBRARY_PATH` when launching Hermes?