> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/getzep/graphiti/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Install Graphiti with your preferred package manager and backend

## Requirements

Before installing Graphiti, ensure you have:

* **Python 3.10 or higher**
* **A graph database** (one of the following):
  * Neo4j 5.26+
  * FalkorDB 1.1.2+
  * Kuzu 0.11.2+
  * Amazon Neptune Database Cluster or Neptune Analytics Graph
* **An LLM provider API key** (OpenAI recommended)

<Warning>
  Graphiti works best with LLM services that support Structured Output (such as OpenAI and Gemini). Using other services may result in incorrect output schemas and ingestion failures, particularly with smaller models.
</Warning>

## Basic Installation

Install Graphiti using your preferred package manager:

<CodeGroup>
  ```bash pip theme={null}
  pip install graphiti-core
  ```

  ```bash uv theme={null}
  uv add graphiti-core
  ```

  ```bash poetry theme={null}
  poetry add graphiti-core
  ```
</CodeGroup>

The basic installation includes:

* Neo4j driver support (default)
* OpenAI LLM and embedding support
* Core dependencies (Pydantic, tenacity, numpy)

## Graph Database Backends

Graphiti supports multiple graph database backends through optional dependencies.

<Tabs>
  <Tab title="Neo4j">
    Neo4j is the default backend and is included in the basic installation.

    ### Setup

    <Steps>
      <Step title="Install Neo4j Desktop">
        Download and install [Neo4j Desktop](https://neo4j.com/download/) for a user-friendly interface to manage Neo4j instances.
      </Step>

      <Step title="Create a Database">
        In Neo4j Desktop:

        1. Create a new project
        2. Add a local DBMS
        3. Set a password
        4. Start the DBMS
      </Step>

      <Step title="Configure Connection">
        ```python theme={null}
        from graphiti_core import Graphiti

        graphiti = Graphiti(
            uri="bolt://localhost:7687",
            user="neo4j",
            password="your_password"
        )
        ```
      </Step>
    </Steps>

    <Tip>
      Neo4j Desktop provides a browser interface at `http://localhost:7474` for visualizing your knowledge graph.
    </Tip>
  </Tab>

  <Tab title="FalkorDB">
    FalkorDB is a lightweight, Redis-compatible graph database that's easy to set up with Docker.

    ### Installation

    ```bash theme={null}
    pip install graphiti-core[falkordb]
    # or
    uv add graphiti-core[falkordb]
    ```

    ### Setup with Docker

    ```bash theme={null}
    docker run -p 6379:6379 -p 3000:3000 -it --rm falkordb/falkordb:latest
    ```

    ### Configure Connection

    ```python theme={null}
    from graphiti_core import Graphiti
    from graphiti_core.driver.falkordb_driver import FalkorDriver

    driver = FalkorDriver(
        host="localhost",
        port=6379,
        username=None,  # Optional
        password=None,  # Optional
        database="my_graph"  # Optional, defaults to "default_db"
    )

    graphiti = Graphiti(graph_driver=driver)
    ```

    <Info>
      FalkorDB provides a browser interface at `http://localhost:3000` when using the Docker image.
    </Info>
  </Tab>

  <Tab title="Kuzu">
    Kuzu is an embedded graph database that doesn't require a separate server.

    ### Installation

    ```bash theme={null}
    pip install graphiti-core[kuzu]
    # or
    uv add graphiti-core[kuzu]
    ```

    ### Configure Connection

    ```python theme={null}
    from graphiti_core import Graphiti
    from graphiti_core.driver.kuzu_driver import KuzuDriver

    driver = KuzuDriver(db="/tmp/graphiti.kuzu")
    graphiti = Graphiti(graph_driver=driver)
    ```

    <Tip>
      Kuzu is ideal for development and testing since it requires no server setup.
    </Tip>
  </Tab>

  <Tab title="Amazon Neptune">
    Amazon Neptune is a fully managed graph database service in AWS.

    ### Installation

    ```bash theme={null}
    pip install graphiti-core[neptune]
    # or
    uv add graphiti-core[neptune]
    ```

    ### Configure Connection

    ```python theme={null}
    from graphiti_core import Graphiti
    from graphiti_core.driver.neptune_driver import NeptuneDriver

    driver = NeptuneDriver(
        host="neptune-db://<cluster-endpoint>",  # For Neptune Database
        # OR
        # host="neptune-graph://<graph-identifier>",  # For Neptune Analytics
        aoss_host="<opensearch-serverless-host>",
        port=8182,  # Optional, defaults to 8182
        aoss_port=443  # Optional, defaults to 443
    )

    graphiti = Graphiti(graph_driver=driver)
    ```

    <Note>
      Amazon Neptune requires an OpenSearch Serverless collection as the full-text search backend.
    </Note>
  </Tab>
</Tabs>

## LLM Providers

Graphiti supports multiple LLM providers. OpenAI is the default and recommended option.

<Tabs>
  <Tab title="OpenAI">
    OpenAI is included in the basic installation and is the default LLM provider.

    ### Setup

    ```bash theme={null}
    export OPENAI_API_KEY=your_openai_api_key
    ```

    ```python theme={null}
    from graphiti_core import Graphiti

    # Uses OpenAI by default
    graphiti = Graphiti(uri, user, password)
    ```

    <Info>
      Graphiti defaults to using `gpt-4o-mini` for inference and `text-embedding-3-small` for embeddings.
    </Info>
  </Tab>

  <Tab title="Azure OpenAI">
    Use Azure's OpenAI service for enterprise deployments.

    ### Setup

    ```python theme={null}
    from openai import AsyncOpenAI
    from graphiti_core import Graphiti
    from graphiti_core.llm_client.azure_openai_client import AzureOpenAILLMClient
    from graphiti_core.llm_client.config import LLMConfig
    from graphiti_core.embedder.azure_openai import AzureOpenAIEmbedderClient

    # Initialize Azure OpenAI client
    azure_client = AsyncOpenAI(
        base_url="https://your-resource.openai.azure.com/openai/v1/",
        api_key="your-api-key",
    )

    # Create clients
    llm_client = AzureOpenAILLMClient(
        azure_client=azure_client,
        config=LLMConfig(
            model="gpt-4o-mini",  # Your deployment name
            small_model="gpt-4o-mini"
        )
    )

    embedder_client = AzureOpenAIEmbedderClient(
        azure_client=azure_client,
        model="text-embedding-3-small"  # Your deployment name
    )

    # Initialize Graphiti
    graphiti = Graphiti(
        uri, user, password,
        llm_client=llm_client,
        embedder=embedder_client,
    )
    ```
  </Tab>

  <Tab title="Anthropic">
    Use Claude models for LLM inference.

    ### Installation

    ```bash theme={null}
    pip install graphiti-core[anthropic]
    # or
    uv add graphiti-core[anthropic]
    ```

    ### Setup

    ```python theme={null}
    from graphiti_core import Graphiti
    from graphiti_core.llm_client.anthropic_client import AnthropicClient
    from graphiti_core.llm_client.config import LLMConfig

    llm_client = AnthropicClient(
        config=LLMConfig(
            api_key="your-anthropic-api-key",
            model="claude-3-5-sonnet-20241022"
        )
    )

    graphiti = Graphiti(
        uri, user, password,
        llm_client=llm_client
    )
    ```
  </Tab>

  <Tab title="Google Gemini">
    Use Google's Gemini models for LLM, embeddings, and reranking.

    ### Installation

    ```bash theme={null}
    pip install graphiti-core[google-genai]
    # or
    uv add graphiti-core[google-genai]
    ```

    ### Setup

    ```python theme={null}
    from graphiti_core import Graphiti
    from graphiti_core.llm_client.gemini_client import GeminiClient, LLMConfig
    from graphiti_core.embedder.gemini import GeminiEmbedder, GeminiEmbedderConfig
    from graphiti_core.cross_encoder.gemini_reranker_client import GeminiRerankerClient

    api_key = "your-google-api-key"

    graphiti = Graphiti(
        uri, user, password,
        llm_client=GeminiClient(
            config=LLMConfig(
                api_key=api_key,
                model="gemini-2.0-flash"
            )
        ),
        embedder=GeminiEmbedder(
            config=GeminiEmbedderConfig(
                api_key=api_key,
                embedding_model="embedding-001"
            )
        ),
        cross_encoder=GeminiRerankerClient(
            config=LLMConfig(
                api_key=api_key,
                model="gemini-2.5-flash-lite"
            )
        )
    )
    ```
  </Tab>

  <Tab title="Ollama (Local)">
    Run local LLMs for privacy and cost savings.

    ### Installation

    ```bash theme={null}
    # Install Ollama from https://ollama.ai

    # Pull models
    ollama pull deepseek-r1:7b
    ollama pull nomic-embed-text
    ```

    ### Setup

    ```python theme={null}
    from graphiti_core import Graphiti
    from graphiti_core.llm_client.config import LLMConfig
    from graphiti_core.llm_client.openai_generic_client import OpenAIGenericClient
    from graphiti_core.embedder.openai import OpenAIEmbedder, OpenAIEmbedderConfig
    from graphiti_core.cross_encoder.openai_reranker_client import OpenAIRerankerClient

    llm_config = LLMConfig(
        api_key="ollama",  # Placeholder
        model="deepseek-r1:7b",
        small_model="deepseek-r1:7b",
        base_url="http://localhost:11434/v1",
    )

    llm_client = OpenAIGenericClient(config=llm_config)

    graphiti = Graphiti(
        uri, user, password,
        llm_client=llm_client,
        embedder=OpenAIEmbedder(
            config=OpenAIEmbedderConfig(
                api_key="ollama",
                embedding_model="nomic-embed-text",
                embedding_dim=768,
                base_url="http://localhost:11434/v1",
            )
        ),
        cross_encoder=OpenAIRerankerClient(
            client=llm_client,
            config=llm_config
        ),
    )
    ```

    <Warning>
      Use `OpenAIGenericClient` (not `OpenAIClient`) for Ollama and other OpenAI-compatible providers.
    </Warning>
  </Tab>

  <Tab title="Groq">
    Use Groq for fast inference with open-source models.

    ### Installation

    ```bash theme={null}
    pip install graphiti-core[groq]
    # or
    uv add graphiti-core[groq]
    ```

    ### Setup

    ```python theme={null}
    from graphiti_core import Graphiti
    from graphiti_core.llm_client.groq_client import GroqClient
    from graphiti_core.llm_client.config import LLMConfig

    llm_client = GroqClient(
        config=LLMConfig(
            api_key="your-groq-api-key",
            model="llama-3.3-70b-versatile"
        )
    )

    graphiti = Graphiti(
        uri, user, password,
        llm_client=llm_client
    )
    ```
  </Tab>
</Tabs>

## Optional Dependencies

Graphiti offers several optional dependencies for extended functionality:

### Voyage AI Embeddings

Use Voyage AI for state-of-the-art embeddings:

```bash theme={null}
pip install graphiti-core[voyageai]
```

### Sentence Transformers

Use local embedding models:

```bash theme={null}
pip install graphiti-core[sentence-transformers]
```

### OpenTelemetry Tracing

Enable distributed tracing for observability:

```bash theme={null}
pip install graphiti-core[tracing]
```

### Multiple Extras

Install multiple optional dependencies at once:

```bash theme={null}
pip install graphiti-core[falkordb,anthropic,google-genai,voyageai]
```

## Performance Tuning

### Concurrency Control

Graphiti's ingestion pipelines support high concurrency. Control this with the `SEMAPHORE_LIMIT` environment variable:

```bash theme={null}
# Default (low concurrency to avoid rate limits)
export SEMAPHORE_LIMIT=10

# Higher concurrency for better performance (if your LLM provider allows)
export SEMAPHORE_LIMIT=50

# Lower concurrency to avoid 429 rate limit errors
export SEMAPHORE_LIMIT=5
```

<Info>
  By default, `SEMAPHORE_LIMIT` is set to `10` to help prevent 429 rate limit errors from your LLM provider. Increase this value if your provider supports higher throughput.
</Info>

## Environment Variables

Common environment variables for Graphiti:

```bash .env theme={null}
# LLM Provider
OPENAI_API_KEY=your_openai_api_key

# Neo4j Connection
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=password

# FalkorDB Connection
FALKORDB_HOST=localhost
FALKORDB_PORT=6379
FALKORDB_USERNAME=  # Optional
FALKORDB_PASSWORD=  # Optional

# Amazon Neptune
NEPTUNE_HOST=neptune-db://your-cluster-endpoint
NEPTUNE_PORT=8182
AOSS_HOST=your-opensearch-host
AOSS_PORT=443

# Performance
SEMAPHORE_LIMIT=10

# Telemetry (opt-out)
GRAPHITI_TELEMETRY_ENABLED=false
```

## Telemetry

Graphiti collects anonymous usage statistics to improve the framework. This includes:

* System information (OS, Python version)
* Graphiti version
* Provider choices (LLM, database, embedder)

**Data NOT collected:**

* Personal information or identifiers
* API keys or credentials
* Your data, queries, or graph content
* IP addresses or hostnames

### Disable Telemetry

To opt out of telemetry:

```bash theme={null}
export GRAPHITI_TELEMETRY_ENABLED=false
```

Or in your Python code:

```python theme={null}
import os
os.environ['GRAPHITI_TELEMETRY_ENABLED'] = 'false'
```

<Note>
  Telemetry is automatically disabled during test runs when pytest is detected.
</Note>

## Verify Installation

Verify your installation with this simple script:

```python verify.py theme={null}
import asyncio
from graphiti_core import Graphiti
from graphiti_core.nodes import EpisodeType
from datetime import datetime, timezone

async def verify():
    # Initialize Graphiti (adjust connection parameters)
    graphiti = Graphiti(
        "bolt://localhost:7687",
        "neo4j",
        "password"
    )
    
    try:
        # Add a test episode
        await graphiti.add_episode(
            name="Test Episode",
            episode_body="Test content",
            source=EpisodeType.text,
            reference_time=datetime.now(timezone.utc)
        )
        print("✓ Installation verified successfully!")
    finally:
        await graphiti.close()

if __name__ == "__main__":
    asyncio.run(verify())
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Build your first knowledge graph
  </Card>

  <Card title="Core Concepts" icon="book" href="/concepts/episodes">
    Learn about episodes, nodes, and edges
  </Card>

  <Card title="Search Guide" icon="magnifying-glass" href="/guides/search">
    Master hybrid search and reranking
  </Card>

  <Card title="Examples" icon="code" href="https://github.com/getzep/graphiti/tree/main/examples">
    Explore example projects
  </Card>
</CardGroup>