Skip to main content
Set up your environment and install Cognee to start building AI memory.
Python 3.9 – 3.12 is required to run Cognee.

​
Setup Notes

  • We recommend creating a .env file in your project root
  • Cognee supports many configuration options, and a .env file keeps them organized
You have two main options for configuring LLM and embedding providers:Option 1: OpenAI (Simplest)
  • Single API key handles both LLM and embeddings
  • Uses gpt-4o-mini for LLM and text-embedding-3-small 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.
  • We recommend using uv for virtual environment management
  • Run the following commands to create and activate a virtual environment:
uv venv && source .venv/bin/activate
On Windows the setup steps differ slightly from Linux/macOS.Virtual environment activationUse PowerShell or Command Prompt instead of source:
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
Creating the .env fileCopy the template from the project root, then open it in any text editor (Notepad, VS Code, etc.):
Copy-Item .env.template .env
The .env file must be saved in the project root — the same directory from which you run Python. Cognee calls load_dotenv() at import time and searches upward from the working directory.Path values on WindowsWhen 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"
Setting env vars without a .env file (optional)If you prefer to set variables directly in your shell session instead of using a file:
$env: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.
Line endingsPython-dotenv handles both Windows (CRLF) and Unix (LF) line endings automatically, so line endings are not a concern.
  • PostgreSQL database is required if you plan to use PostgreSQL as your relational database (requires postgres extra)

​
Setup

​
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]"
If you already know the stack you want, these combinations cover the most common setups:
Use caseInstall
PostgreSQL as the database backenduv pip install "cognee[postgres]"
Neo4j graph store + AWS S3 storageuv pip install "cognee[neo4j,aws]"
Distributed execution on Modaluv pip install "cognee[distributed]"
Code graph analysisuv pip install "cognee[codegraph]"
Full monitoring (Sentry + Langfuse + OpenTelemetry)uv pip install "cognee[monitoring]"
Web scraping + extended document formatsuv pip install "cognee[scraping,docs]"
BAML structured output backenduv pip install "cognee[baml]"
Anthropic Claude modelsuv pip install "cognee[anthropic]"
These extras install provider SDKs. You still need to set the corresponding environment variables. See LLM Providers and Embedding Providers.
ExtraPackages installedWhen to use
anthropicanthropic>=0.27Use Claude models (claude-3-5-sonnet, etc.)
groqgroq>=0.8.0,<1.0.0Use Groq-hosted inference
mistralmistral-common, mistralaiUse Mistral AI models
huggingfacetransformers>=4.46.3,<5Use HuggingFace models for LLM or embeddings
ollamatransformers>=4.46.3,<5Use Ollama for local model serving
llama-cppllama-cpp-python[server]>=0.3.0Run GGUF models locally via llama.cpp
azureazure-identity>=1.15.0,<2Azure OpenAI or other Azure-hosted models
fastembedfastembed<=0.6.0, onnxruntimeFast local embeddings without a GPU
There is no separate gemini extra. Gemini is supported through litellm, which is already part of the base installation.
ExtraPackages installedWhen to use
postgrespsycopg2, pgvector, asyncpgUse PostgreSQL as relational DB and pgvector as vector store
postgres-binarypsycopg2-binary, pgvector, asyncpgSame as postgres but uses pre-compiled binary wheels
neo4jneo4j>=5.28.0,<6Use Neo4j as the graph store
neptunelangchain_aws>=0.2.22Use Amazon Neptune as the graph store
chromadbchromadb>=0.6,<0.7, pypikaUse ChromaDB as the vector store
graphitigraphiti-core>=0.7.0,<0.8Use Graphiti for temporal knowledge graphs
ExtraPackages installedWhen to use
docsunstructured (with csv, doc, docx, epub, md, ppt, pptx, xlsx, pdf, and more), lxmlParse Office documents, PDFs via unstructured, and other rich formats beyond the built-in PyPDF support
doclingdocling>=2.54, transformers>=4.55Use Docling for advanced document parsing
scrapingtavily-python, beautifulsoup4, playwright, lxml, protego, APSchedulerWeb scraping, URL ingestion, and scheduled crawling
codegraphfastembed, transformers, tree-sitter, tree-sitter-pythonBuild code graphs from Python repositories
langchainlangsmith, langchain_text_splitters, langchain-coreUse LangChain text splitters or LangSmith tracing
llama-indexllama-index-core>=0.13.0,<0.14Use LlamaIndex data loaders and connectors
dltdlt[sqlalchemy]>=1.9.0,<2Ingest data via DLT pipelines
ExtraPackages installedWhen to use
distributedmodal>=1.0.5,<2.0.0Run cognee pipelines on Modal for distributed/serverless execution
redisredis>=5.0.3,<6.0.0Use Redis for caching instead of the default in-memory/disk cache
awss3fs[boto3]==2025.3.2Use Amazon S3 for file storage
bamlbaml-py==0.206.0Use BAML as a structured output backend
ExtraPackages installedWhen to use
tracingopentelemetry-api, opentelemetry-sdk, OTLP exporters (gRPC + HTTP)Export traces via OpenTelemetry to any compatible backend
monitoringEverything in tracing plus sentry-sdk[fastapi], langfuseFull monitoring stack: Sentry for errors, Langfuse for LLM observability, OpenTelemetry for traces
posthogposthog>=3.5.0,<4Send usage analytics to PostHog
ExtraPackages installedWhen to use
deepevaldeepeval>=3.0.1,<4Run LLM evaluation benchmarks with DeepEval
evalsplotly, gdown, pandas, matplotlib, scikit-learnInternal evaluation tooling with plotting and metrics
ExtraPackages installedWhen to use
notebooknotebook>=7.1.0,<8Run Jupyter notebooks
devpytest, mypy, ruff, pre-commit, mkdocs, and moreFull development environment for contributing to cognee
debugdebugpy>=1.8.9,<2.0.0Attach a remote debugger (e.g. VS Code) to a running cognee process
If you encounter an ImportError when using a cognee feature, it usually means a required extra has not been installed.
ImportError mentionsInstall
neo4jcognee[neo4j]
modalcognee[distributed]
playwright, tavily, beautifulsoup4cognee[scraping]
unstructuredcognee[docs]
doclingcognee[docling]
fastembedcognee[fastembed] or cognee[codegraph]
tree_sittercognee[codegraph]
psycopg2, asyncpg, pgvectorcognee[postgres] or cognee[postgres-binary]
rediscognee[redis]
s3fs, boto3cognee[aws]
bamlcognee[baml]
anthropiccognee[anthropic]
groqcognee[groq]
mistralaicognee[mistral]
llama_cppcognee[llama-cpp]
opentelemetrycognee[tracing] or cognee[monitoring]
sentry_sdk, langfusecognee[monitoring]
graphiticognee[graphiti]
chromadbcognee[chromadb]
deepevalcognee[deepeval]
dltcognee[dlt]

​
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.