Prerequisites for Code-Graph-RAG: Complete Installation Guide and System Requirements

Code-Graph-RAG requires Python 3.12+, Docker with Docker Compose, CMake, and ripgrep to parse codebases and run the RAG interface, with optional API keys for cloud LLMs or Ollama for local models.

Before you can index repositories and query them with natural language using the vitali87/code-graph-rag toolkit, you must install several system-level dependencies. These prerequisites support the parser layer, graph database, and vector search components that power the cgr CLI.

Core System Requirements

Python 3.12 or Higher

The project strictly requires Python 3.12 or newer, as declared in pyproject.toml at line 6 with requires-python = ">=3.12". This version ensures compatibility with the Tree-sitter bindings and async features used throughout the codebase.

Docker and Docker Compose

You must have Docker Engine and the Docker Compose plugin installed (or Docker Desktop). The cgr daemon up command orchestrates containers defined in codebase_rag/docker-compose.yaml, which spin up Memgraph for graph storage and Qdrant for vector search.

CMake for Native Extensions

CMake is required to build the pymgclient native extension—the Memgraph Python driver that communicates via the Bolt protocol. Without CMake, the Python client cannot compile, blocking graph database connectivity.

Ripgrep for Fast Text Search

The rg (ripgrep) command-line tool must be available in your PATH. The CLI uses it for file-level grep operations and pattern matching during codebase parsing, as implemented in the CLI module.

Package Management and Installation

Using uv (Recommended)

The documentation recommends using uv to handle the extra-dependency syntax and provide faster environment isolation. Install the package with full language support and semantic search capabilities:

uv tool install "code-graph-rag[treesitter-full,semantic]"

The [treesitter-full,semantic] extras pull in every Tree-sitter grammar and the UniXcoder embedding library as defined in pyproject.toml.

Alternative with pip or pipx

You can also use pipx or pip with the same extras syntax:

pipx install "code-graph-rag[treesitter-full,semantic]"

Optional LLM Requirements

Cloud Model API Keys

If you plan to use hosted LLM services for code generation and answering queries, obtain a Google Gemini API key or an OpenAI API key. These are only required for cloud-based semantic search and query answering features.

Local Model Support with Ollama

For completely offline usage, install and run Ollama. This enables local LLM inference without sending code to external APIs, supporting private deployments where cloud access is restricted.

Verifying Your Installation

Before parsing your first repository, verify that all components are correctly installed and reachable. Run the built-in health check:

cgr doctor

This command executes the verification logic defined in codebase_rag/health.py, checking for Docker, CMake, ripgrep, and Python version compatibility.

Why These Prerequisites Matter

Understanding the architecture clarifies why each dependency is mandatory:

• Parser Layer: Tree-sitter grammars compile into native Python bindings requiring a C toolchain (CMake)
• Graph Layer: Memgraph runs inside Docker containers orchestrated by docker compose, while pymgclient requires compilation
• Search Layer: Semantic search depends on either cloud API keys or local Ollama instances for embedding generation

Starting the Services

Once prerequisites are met, start the bundled infrastructure:

cgr daemon up

This reads codebase_rag/docker-compose.yaml and launches both the Memgraph graph database and Qdrant vector store, waiting until health checks pass before returning control.

Summary

• Python 3.12+ is strictly required as defined in pyproject.toml with requires-python = ">=3.12"
• Docker and Docker Compose run the Memgraph and Qdrant containers via codebase_rag/docker-compose.yaml
• CMake compiles the pymgclient native extension for graph database connectivity over Bolt protocol
• Ripgrep (rg) enables fast text search operations in the CLI
• Use uv or pipx to install with [treesitter-full,semantic] extras for full functionality
• Optional API keys (Google Gemini/OpenAI) or Ollama enable LLM-powered query features
• Verify setup with cgr doctor implemented in codebase_rag/health.py

Frequently Asked Questions

Can I use Python 3.11 or earlier with Code-Graph-RAG?

No. The pyproject.toml explicitly sets requires-python = ">=3.12". The codebase relies on language features and library compatibility only available in Python 3.12 and newer, particularly for the Tree-sitter bindings.

Why is CMake required if I'm installing from PyPI?

CMake is needed to compile the pymgclient native extension, which is a dependency of the Memgraph Python client. Even when installing from PyPI, this package requires compilation against system libraries to enable Bolt protocol communication with the graph database.

Do I need API keys if I only want to parse code without querying?

No. Cloud API keys (Google Gemini or OpenAI) and Ollama are only required for the RAG query features that generate natural language answers. You can parse repositories and build the code graph using cgr start without any LLM configuration.

What if Docker is running but cgr daemon up fails?

Ensure you have the Docker Compose plugin installed and that your user has permissions to access the Docker daemon. The CLI reads codebase_rag/docker-compose.yaml and requires both Docker Engine and Compose to be functional, not just the Docker binary itself. Run cgr doctor to diagnose specific connectivity issues.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}