Installation

Set up your environment and install Cognee to start building AI memory.

Python 3.10 – 3.14 is required to run Cognee.

Using Claude Code or another LLM to set up Cognee? Install Cognee’s agent skills first — start with cognee-install — so the assistant checks Python versions, provider settings, extras, and the first smoke test in the right order.

Setup Notes

Environment Configuration

We recommend creating a .env file in your project root
Cognee supports many configuration options, and a .env file keeps them organized

API Keys & Models

You have two main options for configuring LLM and embedding providers:Option 1: OpenAI (Simplest)

Single API key handles both LLM and embeddings
Uses openai/gpt-5.6-luna for LLM and openai/text-embedding-3-large for embeddings by default
Works out of the box with minimal configuration

Option 2: Other Providers

Configure both LLM and embedding providers separately
Supports Gemini, Anthropic, Ollama, and more
Requires setting both LLM_* and EMBEDDING_* variables

By default, Cognee uses OpenAI for both LLMs and embeddings. If you change the LLM provider but don’t configure embeddings, it will still default to OpenAI.

Virtual Environment

We recommend creating a virtual environment before installing Cognee. Use whichever tool you prefer — uv is fast, but the standard library venv works just as well if you don’t use uv.The activation command depends on your shell, not just your operating system. source is Unix-only; on Windows, PowerShell and Command Prompt each have their own activation script inside .venv\Scripts\.

macOS / Linux
Windows (PowerShell)
Windows (Command Prompt)

# uv
uv venv
source .venv/bin/activate

# or standard venv + pip
python -m venv .venv
source .venv/bin/activate

# uv
uv venv
.\.venv\Scripts\Activate.ps1

# or standard venv + pip
python -m venv .venv
.\.venv\Scripts\Activate.ps1

:: uv
uv venv
.venv\Scripts\activate.bat

:: or standard venv + pip
python -m venv .venv
.venv\Scripts\activate.bat

activate.bat is the Command Prompt script — it does not work in PowerShell, and Activate.ps1 does not work in Command Prompt.

If PowerShell blocks activation with an execution-policy error, or import cognee later fails because the wrong interpreter is active, see the Windows Setup accordion below.

Download Size & Offline Installs

As of v1.6.0, Cognee wheels bundle the embedded graph engine’s JSON extension binaries, so the default graph store never has to download them at runtime and works on offline or firewall-restricted hosts. As of v1.6.1 the bundle also ships in the source distribution, so a wheel built from the sdist — uv build, or any --no-binary install — carries it too. See Graph Stores for the two platforms the bundle does not cover.This makes the wheel noticeably larger — roughly 7 MB before bundling, and roughly 19 MB with the two engine versions currently bundled, almost all of the difference being the Windows binaries. The size tracks the graph engine version range in Cognee’s own dependencies, so it moves whenever that range does: each additional bundled version adds about 5 MB. The source distribution was unchanged in v1.6.0 and grows by roughly the same bundle from v1.6.1 on, and the Docker image grows by about 15 MB. Installing still needs network access for Cognee itself and its dependencies; only the extension download is removed.

uv Projects (uv add)

If your project is managed by uv — it has a pyproject.toml, usually created with uv init — use uv add instead of uv pip install. It records Cognee in your pyproject.toml dependencies, updates uv.lock, and installs it into the project’s .venv:

uv add cognee

Extras go in the package spec exactly as with pip. Quote it so your shell does not interpret the brackets:

uv add "cognee[postgres]"
uv add "cognee[neo4j,aws]"

Then run your code with uv run python your_script.py, which uses the project environment without manual activation.Two things to know:

uv add requires a uv project. Run from a directory with no pyproject.toml (a plain uv venv environment, for example), it fails — use uv pip install cognee there instead.
Cognee requires Python >=3.10,<3.15, so your project’s own requires-python must stay inside that range or resolution fails.

Windows Setup

On Windows the setup steps differ slightly from Linux/macOS.

Install uv

Install uv with the official standalone installer, which adds uv to your PATH automatically:

PowerShell
Command Prompt (CMD)

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

If you ran pip install uv and then hit uv : The term 'uv' is not recognized..., the package installed but Python’s scripts folder is not available on your PATH. You can either reinstall uv with the standalone installer above, add Python’s scripts folder to PATH, or call uv through Python instead:

python -m uv pip install cognee

Create and Activate the Virtual Environment

Once uv --version works, create the environment and activate it with the script that matches your shell — PowerShell uses .venv\Scripts\Activate.ps1, Command Prompt uses .venv\Scripts\activate.bat:

PowerShell
Command Prompt (CMD)

uv venv
.\.venv\Scripts\Activate.ps1

If you see an execution-policy error, run this first (current user only):

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

uv venv
.venv\Scripts\activate.bat

Verify the Python Interpreter

After installing Cognee in the Setup section, confirm the active interpreter can import it:

PowerShell
Command Prompt (CMD)

python -c "import cognee; print(cognee.__file__)"

python -c "import cognee; print(cognee.__file__)"

The printed path should point inside your .venv folder.A common Windows error is ModuleNotFoundError: No module named 'cognee' even though the install succeeded. This happens when the script runs with system Python instead of the venv interpreter — for example after opening a new terminal without re-activating, double-clicking a .py file, or an IDE configured to use the global interpreter.First confirm which Python the active terminal uses. The .venv\Scripts\python.exe path should be selected:

PowerShell
Command Prompt (CMD)

Get-Command python

where python

If it does not, re-activate the environment in that terminal:

PowerShell
Command Prompt (CMD)

.\.venv\Scripts\Activate.ps1

.venv\Scripts\activate.bat

To bypass activation entirely, call the venv interpreter explicitly when running your script:

PowerShell
Command Prompt (CMD)

.\.venv\Scripts\python.exe your_script.py

.venv\Scripts\python.exe your_script.py

In an IDE (VS Code, PyCharm), select the .venv interpreter as the project interpreter so the Run button uses it.

Configure Environment Files and Paths

Copy the template from the project root, then open it in any text editor (Notepad, VS Code, etc.):

PowerShell
Command Prompt (CMD)

Copy-Item .env.template .env

copy .env.template .env

Save the .env file in your project root — the same directory from which you run Python. At import time Cognee runs its own search for the file: the working directory and its parents first, stopping at the project root (the nearest directory holding .git or pyproject.toml), then the installed package’s directory tree. Set COGNEE_ENV_FILE to pin a specific file instead. See How .env Is Loaded for the full resolution order.When setting DATA_ROOT_DIRECTORY or SYSTEM_ROOT_DIRECTORY in your .env file, use forward slashes or double backslashes — single backslashes are not valid in .env values:

# Forward slashes (recommended)
DATA_ROOT_DIRECTORY="C:/Users/YourName/cognee/.cognee_data"
SYSTEM_ROOT_DIRECTORY="C:/Users/YourName/cognee/.cognee_system"

# Or double backslashes
DATA_ROOT_DIRECTORY="C:\\Users\\YourName\\cognee\\.cognee_data"

A ~ home-directory prefix also works and is cross-platform:

DATA_ROOT_DIRECTORY="~/.cognee_data"

If you prefer to set variables directly in your shell session instead of using a file:

PowerShell
Command Prompt (CMD)

$env:LLM_API_KEY = "your_openai_api_key"

set LLM_API_KEY=your_openai_api_key

Variables set this way are session-scoped and lost when the terminal closes. A .env file is recommended for persistent configuration.

Python-dotenv handles both Windows (CRLF) and Unix (LF) line endings automatically, so line endings are not a concern.

Graph Database Fails to Open (Could not find lbug C API shared library)

If the first call that opens the graph database fails with:

RuntimeError: Could not find lbug C API shared library.

the cause is missing OpenSSL DLLs: the Windows wheels of ladybug (Cognee’s default graph database) stopped shipping the OpenSSL 3 libraries their native extension loads, so the extension fails to import and ladybug falls back to a backend whose shared library is not distributed at all.Cognee handles this for you. It supplies those libraries from CPython’s own OpenSSL 3 — copying them into a per-interpreter cache directory under the names the extension expects and adding that directory to the DLL search path — automatically, at import time, in the main process and in every database worker process. There is nothing to install, configure, or set in .env. The workaround turns itself off on non-Windows platforms and on installs whose ladybug wheel ships its own OpenSSL.The one case it cannot cover is an interpreter that has no OpenSSL 3 to borrow: CPython 3.10 on Windows links OpenSSL 1.1 instead, and embedded distributions ship no DLLs folder at all. Cognee supports Python 3.10, so if you see this error, check which version the environment runs:

PowerShell
Command Prompt (CMD)

python --version

python --version

If it reports 3.10, that is the cause. On Windows, use Python 3.11 or newer from a standard python.org or uv-managed installation — not an embedded distribution. Recreate the virtual environment with that interpreter and reinstall Cognee:

PowerShell
Command Prompt (CMD)

uv venv --python 3.12
.\.venv\Scripts\Activate.ps1
uv pip install cognee

uv venv --python 3.12
.venv\Scripts\activate.bat
uv pip install cognee

Optional

Database

PostgreSQL database is required if you plan to use PostgreSQL as your relational database (requires postgres extra)

Setup

OpenAI (Recommended)
Other Providers (Gemini, Anthropic, etc.)
Ollama (Local, No API Key)

Environment: Add your OpenAI API key to your .env file:

LLM_API_KEY="your_openai_api_key"

Installation: Install Cognee with the default package, using whichever tool manages your environment. With pip or uv pip, activate the virtual environment first; in a uv project, uv add installs into the project’s .venv directly:

pip install cognee

uv pip install cognee

uv add cognee

What this gives you: Cognee installed with default local databases (SQLite, LanceDB, Kuzu) — no external servers required.

This single API key handles both LLM and embeddings. The defaults are openai/gpt-5.6-luna for the LLM and openai/text-embedding-3-large (3072 dimensions) for embeddings.

Environment: Configure both LLM and embedding providers in your .env file. Here is an example for Gemini:

# LLM
LLM_PROVIDER="gemini"
LLM_MODEL="gemini/gemini-flash-latest"
LLM_API_KEY="your_gemini_api_key"

# Embeddings
EMBEDDING_PROVIDER="gemini"
EMBEDDING_MODEL="gemini/gemini-embedding-001"
EMBEDDING_API_KEY="your_gemini_api_key"

Make sure to configure both LLM and embedding settings. If you only set one, the other will default to OpenAI.

Installation: Install Cognee, then add provider-specific extras only when needed:

Provider path	Install command
Gemini through Google AI Studio	No extra package
Gemini through Vertex AI	`uv pip install google-cloud-aiplatform`
Anthropic	`uv pip install "cognee[anthropic]"`
Ollama	`uv pip install "cognee[ollama]"`
Groq	`uv pip install "cognee[groq]"`
Mistral	`uv pip install "cognee[mistral]"`

What this gives you: Cognee installed with your chosen providers and default local databases.For detailed configuration options, see our LLM and Embeddings guides.

Environment: Run both the LLM and embeddings locally with Ollama. Configure both providers in your .env file. Unlike cloud providers, Ollama needs a local base URL (LLM_ENDPOINT / EMBEDDING_ENDPOINT) pointing at your running Ollama server:

# LLM — Ollama
LLM_PROVIDER="ollama"
LLM_MODEL="llama3.1:8b"
LLM_ENDPOINT="http://localhost:11434"
LLM_API_KEY="ollama"

# Embeddings — Ollama
EMBEDDING_PROVIDER="ollama"
EMBEDDING_MODEL="nomic-embed-text:latest"
EMBEDDING_ENDPOINT="http://localhost:11434/api/embed"
EMBEDDING_DIMENSIONS="768"
HUGGINGFACE_TOKENIZER="nomic-ai/nomic-embed-text-v1.5"  # optional, recommended for accurate token counting

LLM_API_KEY="ollama" is a required placeholder — Ollama ignores the value, but Cognee needs it non-empty. LLM_ENDPOINT is the bare host with no path suffix — on the default structured output backend, LiteLLM appends Ollama’s native /api/generate path itself, so a trailing /v1 fails with a 404 (see LLM Providers → Ollama). EMBEDDING_ENDPOINT is handled separately and keeps its /api/embed path. HUGGINGFACE_TOKENIZER is the HuggingFace repo ID of the tokenizer matching your embedding model; it is optional — Cognee no longer requires it at startup — but recommended for accurate token counting.Installation: Install Cognee with the Ollama extra, then pull the models:

uv pip install "cognee[ollama]"
ollama pull llama3.1:8b
ollama pull nomic-embed-text:latest

What this gives you: A fully local setup — no cloud account or API key required.

Configure both LLM and embeddings to a local backend. If you set only one, the other defaults to OpenAI. See the Local Setup guide for an Ollama LLM + Fastembed alternative and troubleshooting.

Extras and Common Installation Combinations

Cognee’s base installation (pip install cognee) includes everything needed to run with OpenAI and the default local databases (SQLite, LanceDB, Kuzu). Optional extras unlock additional providers, integrations, and features. Install one or more extras with:

pip install "cognee[extra1,extra2]"
# or with uv:
uv pip install "cognee[extra1,extra2]"
# or, in a uv project:
uv add "cognee[extra1,extra2]"

The tables below use uv pip install; the same package specs work with pip install and with uv add in a uv project (see the uv Projects note above).

Common installation combinations

If you already know the stack you want, these combinations cover the most common setups:

Use case	Install
PostgreSQL as the database backend	`uv pip install "cognee[postgres]"`
Neo4j graph store + AWS S3 storage	`uv pip install "cognee[neo4j,aws]"`
Code graph analysis	`uv pip install cognee` (nothing extra — the `enola-cli` binary ships with the base install)
OpenTelemetry tracing	`uv pip install "cognee[tracing]"`
Web scraping + extended document formats	`uv pip install "cognee[scraping,docs]"`
Gmail inbox ingestion	`uv pip install "cognee[gmail]"`
BAML structured output backend	`uv pip install "cognee[baml]"`
Anthropic Claude models	`uv pip install "cognee[anthropic]"`
LLM-free graph building (local GLiNER extraction + local embeddings)	`uv pip install "cognee[gliner]"`

LLM & Embedding Providers

These extras install provider SDKs. You still need to set the corresponding environment variables. See LLM Providers and Embedding Providers.

Extra	Packages installed	When to use
`anthropic`	`anthropic>=0.27`	Use Claude models (claude-sonnet-5, etc.)
`groq`	`groq>=0.8.0,<1.0.0`	Use Groq-hosted inference
`mistral`	`mistral-common`, `mistralai`	Use Mistral AI models
`huggingface`	`transformers>=4.46.3,<6`	Use HuggingFace models for LLM or embeddings
`ollama`	`transformers>=4.46.3,<6`	Use Ollama for local model serving
`llama-cpp`	`llama-cpp-python[server]>=0.3.0`	Run GGUF models locally via llama.cpp
`azure`	`azure-identity>=1.15.0,<2`	Azure OpenAI or other Azure-hosted models
`fastembed`	— (empty extra; `fastembed` and `onnxruntime` are core cognee dependencies)	Fast local embeddings without a GPU. Nothing to install — the extra is kept only so `cognee[fastembed]` stays valid
`gliner`	`gliner2[local]>=2.0.0,<3`, `torch>=2.1,<3`, `protobuf>=5.29.6`, `sentencepiece>=0.2.0`, `psutil>=5.9`	Build the knowledge graph and chunk summaries with the local GLiNER demo model instead of the LLM (`GRAPH_EXTRACTOR=gliner_demo`, or the `auto` default with no LLM key configured). Recommended but optional: without it, the first run that needs GLiNER installs the same list itself, taking CPU-only torch from the PyTorch index instead of the CUDA build PyPI serves on Linux. Either way ~750 MB of model weights download on first use. See Installing the runtime

There is no separate gemini extra. Gemini through Google AI Studio is supported through litellm, which is already part of the base installation. Vertex AI for Gemini additionally requires google-cloud-aiplatform.

Vector & Graph Stores

Extra	Packages installed	When to use
`postgres`	`psycopg2`, `pgvector`, `asyncpg`	Use PostgreSQL as relational DB and pgvector as vector store
`postgres-binary`	`psycopg2-binary`, `pgvector`, `asyncpg`	Same as `postgres` but uses pre-compiled binary wheels
`neo4j`	`neo4j>=5.28.0,<6`	Use Neo4j as the graph store
`neptune`	`langchain_aws>=0.2.22`	Use Amazon Neptune as the graph store
`chromadb`	`chromadb>=0.6,<0.7`, `pypika`	Use ChromaDB as the vector store

Data Ingestion & Processing

Extra	Packages installed	When to use
`docs`	`unstructured` (with csv, doc, docx, epub, md, ppt, pptx, xlsx, pdf, and more), `lxml`	Parse Office documents, PDFs via unstructured, and other rich formats beyond the built-in PyPDF support
`docling`	`docling>=2.54`, `transformers>=4.55`	Use Docling for advanced document parsing
`scraping`	`tavily-python`, `beautifulsoup4`, `playwright`, `lxml`, `protego`, `APScheduler`	Web scraping, URL ingestion, and scheduled crawling
`codegraph`	— (empty extra; `enola-cli==0.4.26` is a core cognee dependency)	Build code graphs from code repositories. Nothing to install — the extra is kept only so `cognee[codegraph]` stays valid
`langchain`	`langsmith`, `langchain_text_splitters`, `langchain-core`	Use LangChain text splitters or LangSmith tracing
`llama-index`	`llama-index-core>=0.14.20,<0.15`	Use LlamaIndex data loaders and connectors
`dlt`	— (empty extra; `dlt[sqlalchemy]>=1.9.0,<1.31` and `pandas>=2.2.2,<3.0.0` are core cognee dependencies)	Ingest data via DLT pipelines. Nothing to install — the extra is kept only so `cognee[dlt]` stays valid
`gmail`	`google-api-python-client>=2.100.0,<3`, `google-auth>=2.23.0,<3`, `google-auth-oauthlib>=1.1.0,<2`	Ingest Gmail messages with the bundled Gmail connector or the Gmail integration (from `v1.6.1`; replaces the `cognee-community-connector-gmail` package)
`google-drive`	`google-api-python-client>=2.100.0,<3`, `google-auth>=2.23.0,<3`, `google-auth-oauthlib>=1.1.0,<2`	Sync Drive files through the Google Drive integration (from `v1.6.1`)

Infrastructure & Storage

Extra	Packages installed	When to use
`redis`	`redis>=5.0.3,<6.0.0`	Use Redis for caching instead of the default in-memory/disk cache
`aws`	`s3fs[boto3]==2025.3.2`	Use Amazon S3 for file storage
`baml`	`baml-py==0.206.0`	Use BAML as a structured output backend

Observability & Monitoring

Extra	Packages installed	When to use
`tracing`	`opentelemetry-api`, `opentelemetry-sdk`, OTLP exporters (gRPC + HTTP)	Export traces via OpenTelemetry to any compatible backend
`posthog`	`posthog>=3.5.0,<4`	Send usage analytics to PostHog

Evaluation

Extra	Packages installed	When to use
`deepeval`	`deepeval>=3.0.1,<4`	Run LLM evaluation benchmarks with DeepEval
`evals`	`plotly`, `gdown`, `pandas`, `matplotlib`, `scikit-learn`	Internal evaluation tooling with plotting and metrics

Development & Tooling

Extra	Packages installed	When to use
`notebook`	`notebook>=7.1.0,<8`	Run Jupyter notebooks
`dev`	pytest, mypy, ruff, pre-commit, mkdocs, and more	Full development environment for contributing to cognee
`debug`	`debugpy>=1.8.9,<2.0.0`	Attach a remote debugger (e.g. VS Code) to a running cognee process

Missing dependency errors (ImportError)

If you encounter an ImportError when using a cognee feature, it usually means a required extra has not been installed.

ImportError mentions	Install
`neo4j`	`cognee[neo4j]`
`playwright`, `tavily`, `beautifulsoup4`	`cognee[scraping]`
`unstructured`	`cognee[docs]`
`docling`	`cognee[docling]`
`fastembed`	Nothing to install — `fastembed` is a core cognee dependency; reinstall cognee if the import fails
`gliner2`	`cognee[gliner]` — `cognify()` installs this runtime itself when it needs it, so an `ImportError` here comes mainly from running the GLiNER tasks directly (see Custom GLiNER Extraction), which do not auto-install
`psycopg2`, `asyncpg`, `pgvector`	`cognee[postgres]` or `cognee[postgres-binary]`
`redis`	`cognee[redis]`
`s3fs`, `boto3`	`cognee[aws]`
`baml`	`cognee[baml]`
`anthropic`	`cognee[anthropic]`
`groq`	`cognee[groq]`
`mistralai`	`cognee[mistral]`
`llama_cpp`	`cognee[llama-cpp]`
`opentelemetry`	`cognee[tracing]`
`chromadb`	`cognee[chromadb]`
`deepeval`	`cognee[deepeval]`
`dlt`, `pandas`	Nothing to install — both are core cognee dependencies; reinstall cognee if the import fails
`googleapiclient`, `google-api-python-client`, `google-auth`, `google-auth-oauthlib`	`cognee[gmail]` or `cognee[google-drive]`

Verifying Release Authenticity

Cognee’s release pipeline attaches supply-chain provenance to the packages it publishes: PEP 740 attestations shown in the “Provenance” section of the PyPI project page, plus a GitHub-hosted SLSA build provenance attestation. To confirm a downloaded wheel or sdist was built by CI from topoteretes/cognee:

gh attestation verify ./cognee-<version>-py3-none-any.whl --repo topoteretes/cognee

Which projects this covers

Two PyPI projects are published from this repository, from separate workflows and with different provenance:

PyPI project	Release tag	Notes
`cognee`	`v<version>`	The library. Weekly canaries are versioned `X.Y.Z.devYYYYMMDD` and are not tagged
`cognee-mcp`	`cognee-mcp-v<version>`	The MCP server. Versions independently of the library

cognee-mcp is uploaded with a PyPI API token rather than Trusted Publishing, so its files carry no PEP 740 attestations — there is no “Provenance” section on the cognee-mcp project page to check. The GitHub-hosted SLSA build provenance is still produced for every release the workflow publishes, so that half verifies normally — note the underscore in the distribution filename:

gh attestation verify ./cognee_mcp-<version>-py3-none-any.whl --repo topoteretes/cognee

cognee-mcp 0.5.5 and earlier were uploaded by hand and carry no attestations at all, so verification has nothing to check for them. 0.5.6 was also uploaded by hand, but from the files CI built and attested, so the command above works for it. The subsection below applies to the cognee library only: MCP releases are published and tagged, but create no GitHub release.

Verifying from the GitHub release page

The release pipeline also attaches the built distributions and their attestation to the GitHub release for the tag, so you can verify without querying GitHub’s attestation store:

Asset	What it is
`cognee-<version>-py3-none-any.whl`, `cognee-<version>.tar.gz`	The distributions that were published to PyPI
`cognee-<version>.sigstore.json`	The Sigstore bundle — certificate, signature, and in-toto statement
`cognee-<version>.intoto.jsonl`	The DSSE envelope extracted from that bundle, the shape the SLSA ecosystem expects

Point gh attestation verify at the bundle instead of the repo:

gh attestation verify cognee-<version>-py3-none-any.whl \
  --bundle cognee-<version>.sigstore.json \
  --repo topoteretes/cognee

The upload runs only after the PyPI publish succeeds, so a release page never carries artifacts that did not ship. The weekly PyPI canaries (X.Y.Z.devYYYYMMDD) create no GitHub release and have no assets to verify; .devN pre-releases cut from dev do get them. Releases published before the provenance pipeline landed (August 2026) carry no attestations, so verification has nothing to check for them; releases cut before this asset upload landed have the attestations but no release-page assets, so use the --repo form above for those. For the full mechanism, see Supply-chain provenance & release attestations in the cognee repo.

Next Steps

Run Your First Example

Quickstart TutorialGet started with Cognee by running your first knowledge graph example.

Explore Advanced Features

Core ConceptsDive deeper into Cognee’s powerful features and capabilities.

Getting Started

Core Concepts

Setup Configuration

Guides

Cookbooks

Examples

CLI

OSS

Setup Notes

Setup

Extras and Common Installation Combinations

Verifying Release Authenticity

Which projects this covers

Verifying from the GitHub release page

Next Steps

Run Your First Example

Explore Advanced Features

​Setup Notes

​Setup

​Extras and Common Installation Combinations

​Verifying Release Authenticity

​Which projects this covers

​Verifying from the GitHub release page

​Next Steps

Run Your First Example

Explore Advanced Features

Setup Notes

Setup

Extras and Common Installation Combinations

Verifying Release Authenticity

Which projects this covers

Verifying from the GitHub release page

Next Steps