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

> Learn the prerequisites for Code-Graph-RAG. Install Python 3.12+, Docker, CMake, and ripgrep. Get the complete installation guide and system requirements for efficient code analysis.

- Repository: [Vitali Avagyan/code-graph-rag](https://github.com/vitali87/code-graph-rag)
- Tags: getting-started
- Published: 2026-08-11

---

**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`](https://github.com/vitali87/code-graph-rag/blob/main/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`](https://github.com/vitali87/code-graph-rag/blob/main/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:

```bash
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`](https://github.com/vitali87/code-graph-rag/blob/main/pyproject.toml).

### Alternative with pip or pipx

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

```bash
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:

```bash
cgr doctor

```

This command executes the verification logic defined in [`codebase_rag/health.py`](https://github.com/vitali87/code-graph-rag/blob/main/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:

```bash
cgr daemon up

```

This reads [`codebase_rag/docker-compose.yaml`](https://github.com/vitali87/code-graph-rag/blob/main/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`](https://github.com/vitali87/code-graph-rag/blob/main/pyproject.toml) with `requires-python = ">=3.12"`
- Docker and Docker Compose run the Memgraph and Qdrant containers via [`codebase_rag/docker-compose.yaml`](https://github.com/vitali87/code-graph-rag/blob/main/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`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/health.py)

## Frequently Asked Questions

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

No. The [`pyproject.toml`](https://github.com/vitali87/code-graph-rag/blob/main/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`](https://github.com/vitali87/code-graph-rag/blob/main/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.