Skip to main content
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? Copy the LLM Quickstart Skill first so the assistant checks Python versions, provider settings, extras, and the first smoke test in the right order.

​
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 openai/gpt-5-mini 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.
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.
uv venv && source .venv/bin/activate
On Windows the setup steps differ slightly from Linux/macOS.
Install uv with the official standalone installer, which adds uv to your PATH automatically:
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
Once uv --version works, use 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
After installing Cognee in the Setup section, confirm the active interpreter can import it:
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:
Get-Command python
If it does not, re-activate the environment in that terminal:
.\.venv\Scripts\Activate.ps1
To bypass activation entirely, call the venv interpreter explicitly when running your script:
.\.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.
Copy 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.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:
$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.
Python-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]"
OpenTelemetry tracinguv pip install "cognee[tracing]"
Web scraping + extended document formatsuv pip install "cognee[scraping,docs]"
Gmail inbox ingestionuv pip install "cognee[gmail]"
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 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.
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.14.20,<0.15Use LlamaIndex data loaders and connectors
dltdlt[sqlalchemy]>=1.9.0,<2Ingest data via DLT pipelines
gmaildlt[sqlalchemy]>=1.9.0,<2, google-api-python-client>=2.100.0,<3, google-auth>=2.23.0,<3, google-auth-oauthlib>=1.1.0,<2Ingest Gmail messages into memory (read-only OAuth, incremental sync)
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
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]
graphiticognee[graphiti]
chromadbcognee[chromadb]
deepevalcognee[deepeval]
dltcognee[dlt]
googleapiclient, google-api-python-client, google-auth, google-auth-oauthlibcognee[gmail]

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