# Requirements to Run the Apache HugeGraph AI Project: Complete Setup Guide

> Discover the essential requirements to run the Apache HugeGraph AI project. Learn about Python, UV, HugeGraph Server, and Docker setup.

- Repository: [The Apache Software Foundation/incubator-hugegraph-ai](https://github.com/apache/incubator-hugegraph-ai)
- Tags: getting-started
- Published: 2026-02-24

---

**To run the Apache HugeGraph AI project, you need Python 3.10+, UV package manager 0.7+, HugeGraph Server 1.3+, and optionally Docker 20.10+ for containerized deployment.**

The Apache HugeGraph AI repository is a multi-module workspace combining graph database capabilities, large-language-model (LLM) tooling, and graph machine learning utilities. Understanding the requirements to run the Apache HugeGraph AI project ensures you install only the dependencies necessary for your specific use case, whether you are building RAG applications or training graph neural networks.

## Core System Requirements

Before installing any Python packages, verify your environment meets these baseline specifications.

### Python Runtime

The project requires **Python 3.10 or higher**. This is the minimum version supported across all sub-modules, including `hugegraph-llm` and `hugegraph-python-client`. While some modules may run on older versions, the workspace-wide configuration in [`pyproject.toml`](https://github.com/apache/incubator-hugegraph-ai/blob/main/pyproject.toml) mandates 3.10+ for compatibility with modern async features and type hinting used throughout the codebase.

### Package Manager

You must install **UV 0.7 or higher**, the Rust-based Python package manager. The project uses UV's workspace functionality to resolve dependencies across multiple local packages. Unlike `pip`, UV handles the editable path dependencies defined in the `[tool.uv.workspace]` section of [`pyproject.toml`](https://github.com/apache/incubator-hugegraph-ai/blob/main/pyproject.toml), ensuring that changes in `hugegraph-llm` or `hugegraph-python-client` reflect immediately without reinstallation.

### Graph Database Backend

A running **HugeGraph Server instance (version 1.3+, 1.5+ recommended)** is mandatory. The Python client modules communicate with this server via REST API for graph storage and Gremlin query execution. You can deploy this via Docker using the provided [`docker-compose-network.yml`](https://github.com/apache/incubator-hugegraph-ai/blob/main/docker-compose-network.yml) or install it natively on your host system.

## Workspace Structure and Dependencies

The repository organizes code into a UV workspace with mandatory and optional members.

### Mandatory Modules

According to the [`pyproject.toml`](https://github.com/apache/incubator-hugegraph-ai/blob/main/pyproject.toml) at the repository root, the workspace includes two required members:
- `hugegraph-llm` – Core LLM integration and RAG flows
- `hugegraph-python-client` – Low-level client for HugeGraph Server communication

These are defined under `[tool.uv.workspace]` and are always installed when you run `uv sync`.

### Optional Modules

Additional functionality is available through editable path dependencies:
- `hugegraph-ml` – Graph machine learning utilities
- `vermeer-python-client` – Integration with the Vermeer compute engine

These are not included in the base install but can be added via specific extras flags.

## Optional Dependencies and Feature Extras

The [`pyproject.toml`](https://github.com/apache/incubator-hugegraph-ai/blob/main/pyproject.toml) defines four optional dependency groups under `[project.optional-dependencies]`. Install only what you need to keep your environment lightweight.

### LLM Support (`--extra llm`)

Installs providers and tools for large language model integration:
- `openai`, `ollama`, `litellm` – LLM API clients
- `tiktoken` – Token counting for OpenAI models
- `gradio` – Web interface for demos

### Vector Database Support (`--extra vectordb`)

Required for vector-based RAG retrieval:
- `faiss-cpu` – Facebook AI Similarity Search
- `pyarrow`, `openpyxl` – Data handling utilities

### Machine Learning Support (`--extra ml`)

Installs deep learning frameworks for graph neural networks:
- `torch`, `dgl` (Deep Graph Library)
- `ogb` (Open Graph Benchmark)
- `catboost` – Gradient boosting framework

### Vermeer Compute Engine (`--extra vermeer`)

Adds the `vermeer-python-client` package for distributed graph computing capabilities.

To install all extras simultaneously, use `uv sync --all-extras`.

## Environment Configuration

The project requires a `.env` file for runtime configuration, particularly for Docker deployments.

### Required Environment Variables

Copy the template from `docker/env.template` to `docker/.env` and set:
- `PROJECT_PATH` – Absolute path to your cloned repository root
- `LANGUAGE` – Interface language selection (e.g., `en` or `zh`)
- Vector database and LLM provider credentials

The application watches this file and reloads prompts automatically when changes are detected.

## Step-by-Step Installation

Follow these commands to set up the project from source:

1. **Clone the repository**
   ```bash
   git clone https://github.com/apache/incubator-hugegraph-ai.git
   cd incubator-hugegraph-ai
   ```

2. **Install UV** (if not present)
   ```bash
   curl -LsSf https://astral.sh/uv/install.sh | sh
   ```

3. **Configure environment**
   ```bash
   cp docker/env.template docker/.env
   echo "PROJECT_PATH=$(pwd)" >> docker/.env
   ```

4. **Install dependencies** (replace `llm` with `all-extras` if needed)
   ```bash
   uv sync --extra llm
   ```

5. **Activate virtual environment**
   ```bash
   source .venv/bin/activate
   ```

## Running the Application

You have two primary methods to launch the services.

### Docker Deployment

For the quickest start, use Docker Compose to spin up both HugeGraph Server and the RAG service:

```bash
cd docker
docker compose -f docker-compose-network.yml up -d

```

This creates a shared network allowing the Python services to communicate with the graph database at `http://hugegraph-server:8080`.

### Source Execution

After activating your virtual environment, launch the web demo directly:

```bash
python -m hugegraph_llm.demo.rag_demo.app

```

Access the interface at `http://127.0.0.1:8001`.

## Programmatic Usage Examples

Once installed, interact with the system programmatically using the `SchedulerSingleton` class from `hugegraph_llm.flows.scheduler`.

### Execute a RAG Query

```python
from hugegraph_llm.flows.scheduler import SchedulerSingleton

scheduler = SchedulerSingleton.get_instance()
result = scheduler.schedule_flow(
    "rag_graph_only",
    query="What movies starred Al Pacino?",
    graph_only_answer=True,
    vector_only_answer=False,
)

print("Graph answer:", result.get("graph_only_answer"))

```

### Build a Vector Index

Required before running vector-only RAG:

```python
from hugegraph_llm.flows.scheduler import SchedulerSingleton

examples = [
    {"id": "question1", "gremlin": "g.V().hasLabel('person').valueMap()"},
    {"id": "question2", "gremlin": "g.V().has('name','Alice').out('knows')"},
]

idx_res = SchedulerSingleton.get_instance().schedule_flow(
    "build_examples_index", examples
)
print("Index build result:", idx_res)

```

### Run Graph ML Training

With the `ml` extra installed:

```bash
uv sync --extra ml
source .venv/bin/activate
python hugegraph-ml/src/examples/node_classify.py

```

## Summary

- **Python 3.10+**, **UV 0.7+**, and **HugeGraph Server 1.3+** are mandatory core requirements.
- Install feature-specific dependencies using `uv sync --extra llm`, `--extra ml`, or `--extra vectordb` to avoid bloat.
- Copy `docker/env.template` to `docker/.env` and set `PROJECT_PATH` before running.
- Use **Docker Compose** ([`docker-compose-network.yml`](https://github.com/apache/incubator-hugegraph-ai/blob/main/docker-compose-network.yml)) for integrated server/client deployment, or run the **RAG demo** directly via `python -m hugegraph_llm.demo.rag_demo.app`.
- Programmatic access flows through `SchedulerSingleton` in [`hugegraph_llm/flows/scheduler.py`](https://github.com/apache/incubator-hugegraph-ai/blob/main/hugegraph_llm/flows/scheduler.py).

## Frequently Asked Questions

### What is the minimum Python version required for Apache HugeGraph AI?

The project requires **Python 3.10 or higher**. This requirement is enforced in the root [`pyproject.toml`](https://github.com/apache/incubator-hugegraph-ai/blob/main/pyproject.toml) to ensure compatibility with type hints and async features used across the `hugegraph-llm` and `hugegraph-python-client` modules.

### Is Docker mandatory for running the project?

No, Docker is optional but recommended for quick starts. You can run the HugeGraph Server natively and execute Python components directly using `uv run` or an activated virtual environment. However, the [`docker-compose-network.yml`](https://github.com/apache/incubator-hugegraph-ai/blob/main/docker-compose-network.yml) file provides the simplest way to ensure network connectivity between the graph database and AI services.

### What is the difference between `uv sync --extra llm` and `uv sync --all-extras`?

The `--extra llm` flag installs only the dependencies needed for large language model integration (OpenAI, Ollama, Gradio, etc.), keeping the installation lightweight. The `--all-extras` flag installs every optional dependency group, including machine learning frameworks (PyTorch, DGL) and Vermeer client libraries, which is necessary only if you plan to use all features simultaneously.

### How do I configure the project path for Docker deployments?

You must set the `PROJECT_PATH` variable in `docker/.env`. Copy the template file using `cp docker/env.template docker/.env`, then append your absolute repository path with `echo "PROJECT_PATH=$(pwd)" >> docker/.env`. This allows the Docker containers to mount your local source code correctly.