Installation - GraphRAG

This guide covers everything you need to install and set up GraphRAG on your system.

System requirements

Python version

Python 3.11, 3.12, or 3.13Check your version: python --version

LLM provider

OpenAI API key, Azure OpenAI endpoint, or any LiteLLM-supported provider

GraphRAG uses LiteLLM under the hood, which supports 100+ LLM providers including OpenAI, Azure, Anthropic, Cohere, and more.

Installation methods

Install from PyPI (recommended)

The easiest way to install GraphRAG is via pip from the Python Package Index:

pip install graphrag

This installs the latest stable release (currently version 3.0.5) along with all required dependencies.

We recommend using a virtual environment to avoid conflicts with other Python packages.

Install in a virtual environment

Using a virtual environment is the best practice for Python projects:

# Create project directory
mkdir my-graphrag-project
cd my-graphrag-project

# Create virtual environment
python -m venv .venv

# Activate virtual environment
source .venv/bin/activate

# Install GraphRAG
pip install graphrag

Install from source

For development or to use the latest features from the main branch:

# Clone the repository
git clone https://github.com/microsoft/graphrag.git
cd graphrag

# Create and activate virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install in development mode
pip install -e .

Installing from source gives you the latest code but may include unstable features. Use the PyPI release for production workloads.

Core dependencies

GraphRAG automatically installs these core dependencies:

Language models and AI

graphrag-llm - LLM integration layer
azure-identity - Azure authentication
json-repair - JSON parsing and repair
nltk - Natural language processing
spacy - Advanced NLP capabilities
textblob - Text processing

Graph and vector operations

graphrag-vectors - Vector storage and search
graspologic-native - Graph analytics
networkx - Graph data structures
graphrag-chunking - Text chunking algorithms

Data and storage

graphrag-storage - Storage abstractions
graphrag-cache - LLM caching layer
azure-storage-blob - Azure Blob storage
azure-search-documents - Azure AI Search
pandas - Data manipulation
pyarrow - Parquet file support
numpy - Numerical computing

CLI and utilities

typer - Command-line interface
pydantic - Data validation
tqdm - Progress bars
devtools - Development utilities

Verify installation

After installation, verify that GraphRAG is correctly installed:

# Check GraphRAG version
graphrag --version

# View available commands
graphrag --help

You should see output showing version 3.0.5 (or later) and a list of available commands:

init - Initialize a new GraphRAG workspace
index - Run the indexing pipeline
query - Query your indexed data
update - Update an existing index
prompt-tune - Auto-tune prompts for your data

Provider-specific setup

OpenAI

For OpenAI, you only need an API key:

Get your API key from platform.openai.com
After running graphrag init, add it to your .env file:

.env

GRAPHRAG_API_KEY=sk-your-openai-api-key-here

Your settings.yaml will use OpenAI by default:

settings.yaml

completion_models:
  default_completion_model:
    model_provider: openai
    model: gpt-4-turbo
    api_key: ${GRAPHRAG_API_KEY}

embedding_models:
  default_embedding_model:
    model_provider: openai
    model: text-embedding-3-large
    api_key: ${GRAPHRAG_API_KEY}

Azure OpenAI

For Azure OpenAI, you need additional configuration:

Get your credentials from the Azure Portal:
- API key
- Endpoint URL (e.g., https://your-resource.openai.azure.com)
- Deployment names for your models
- API version (e.g., 2024-02-15-preview)
Add your API key to .env:

.env

GRAPHRAG_API_KEY=your-azure-openai-key

Update settings.yaml with Azure-specific settings:

settings.yaml

completion_models:
  default_completion_model:
    model_provider: azure
    model: gpt-4-turbo
    deployment_name: your-gpt4-deployment
    api_base: https://your-resource.openai.azure.com
    api_version: 2024-02-15-preview
    api_key: ${GRAPHRAG_API_KEY}

embedding_models:
  default_embedding_model:
    model_provider: azure
    model: text-embedding-3-large
    deployment_name: your-embedding-deployment
    api_base: https://your-resource.openai.azure.com
    api_version: 2024-02-15-preview
    api_key: ${GRAPHRAG_API_KEY}

Azure managed identity

For managed identity authentication (no API key needed):

settings.yaml

completion_models:
  default_completion_model:
    model_provider: azure
    model: gpt-4-turbo
    deployment_name: your-gpt4-deployment
    api_base: https://your-resource.openai.azure.com
    api_version: 2024-02-15-preview
    auth_method: azure_managed_identity

Then authenticate using Azure CLI:

az login
az account set --subscription your-subscription-id

Other providers (via LiteLLM)

GraphRAG supports any provider that LiteLLM supports. Examples:

completion_models:
  default_completion_model:
    model_provider: anthropic
    model: claude-3-opus-20240229
    api_key: ${ANTHROPIC_API_KEY}

See the LiteLLM provider documentation for complete configuration examples for 100+ providers.

Optional dependencies

Vector stores

GraphRAG includes LanceDB by default. For other vector stores:

# Azure AI Search (included)
pip install azure-search-documents

# For custom vector stores, implement the vector store interface
# See: https://microsoft.github.io/graphrag/examples_notebooks/custom_vector_store.ipynb

Storage backends

Additional storage options are available:

# Azure Blob Storage (included)
pip install azure-storage-blob

# CosmosDB support (included)
pip install azure-cosmos

Platform-specific considerations

Linux/Unix

No special considerations. Standard pip installation works:

pip install graphrag

macOS

For Apple Silicon (M1/M2) Macs, all dependencies are compatible:

# Standard installation
pip install graphrag

Some users may need to install build tools for native dependencies:

brew install cmake

Windows

Windows users may need Visual C++ build tools for some native dependencies:

Download and install Microsoft C++ Build Tools
Then install GraphRAG:

pip install graphrag

Docker installation

While there’s no official Docker image, you can create your own:

Dockerfile

FROM python:3.11-slim

WORKDIR /app

# Install GraphRAG
RUN pip install graphrag

# Copy your project files
COPY . .

CMD ["graphrag", "--help"]

Build and run:

docker build -t graphrag .
docker run -v $(pwd):/app graphrag index

Upgrading GraphRAG

Upgrade to latest version

pip install --upgrade graphrag

Check for updates

pip list --outdated | grep graphrag

Important: Always run graphrag init --root [path] --force between minor version bumps to ensure you have the latest config format. This will overwrite your settings.yaml and prompts, so backup first if you’ve made customizations.

Migration between major versions

For major version updates (e.g., 2.x to 3.x):

Read the breaking changes document
Backup your existing configuration and data
Use the provided migration notebooks if available to avoid re-indexing
Update your settings.yaml to the new format
Re-run initialization: graphrag init --force

Troubleshooting installation

pip install fails with build errors

This usually indicates missing build tools:macOS:

brew install cmake
xcode-select --install

Linux (Debian/Ubuntu):

sudo apt-get update
sudo apt-get install build-essential cmake

Windows: Install Microsoft C++ Build Tools

Command not found: graphrag

The GraphRAG CLI may not be in your PATH:

Ensure your virtual environment is activated
Try using the full path: python -m graphrag --help
On Windows, you may need to use python -m graphrag instead of graphrag

Import errors after installation

This can happen with dependency conflicts:

Create a fresh virtual environment
Uninstall and reinstall GraphRAG:

pip uninstall graphrag
pip install graphrag

Check for conflicting packages: pip check

SSL certificate errors

If you encounter SSL errors during installation:

# Upgrade pip and certifi
pip install --upgrade pip certifi

# Try installation again
pip install graphrag

For corporate networks behind proxies, configure pip:

pip install --proxy http://proxy.company.com:port graphrag

Next steps

Once GraphRAG is installed:

Quickstart

Follow our quickstart guide to index your first document and run queries.

Configuration

Learn about initialization and configuration options.

CLI reference

Explore all available command-line options.

Development

Set up a development environment to contribute to GraphRAG.

Getting help

If you encounter issues during installation:

Check GitHub Issues for known problems
Ask questions in GitHub Discussions
Review the contributing guide

Get Started

Core Concepts

Indexing

Query Engine

Prompt Tuning

Configuration

Guides

​System requirements

Python version

LLM provider

​Installation methods

​Install from PyPI (recommended)

​Install in a virtual environment

​Install from source

​Core dependencies

​Verify installation

​Provider-specific setup

​OpenAI

​Azure OpenAI

​Azure managed identity

​Other providers (via LiteLLM)

​Optional dependencies

​Vector stores

​Storage backends

​Platform-specific considerations

​Linux/Unix

​macOS

​Windows

​Docker installation

​Upgrading GraphRAG

​Upgrade to latest version

​Check for updates

​Migration between major versions

​Troubleshooting installation

​Next steps

Quickstart

Configuration

CLI reference

Development

​Getting help

Build docs developers (and LLMs) love

System requirements

Installation methods

Install from PyPI (recommended)

Install in a virtual environment

Install from source

Core dependencies

Verify installation

Provider-specific setup

OpenAI

Azure OpenAI

Azure managed identity

Other providers (via LiteLLM)

Optional dependencies

Vector stores

Storage backends

Platform-specific considerations

Linux/Unix

macOS

Windows

Docker installation

Upgrading GraphRAG

Upgrade to latest version

Check for updates

Migration between major versions

Troubleshooting installation

Next steps

Getting help