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.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\.
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.
On Windows the setup steps differ slightly from Linux/macOS.
Install uv with the official standalone installer, which adds uv to your PATH automatically:
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:
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:
If you see an execution-policy error, run this first (current user only):
After installing Cognee in the Setup section, confirm the active interpreter can import it:
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:
If it does not, re-activate the environment in that terminal:
To bypass activation entirely, call the venv interpreter explicitly when running your script:
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.):
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:
A ~ home-directory prefix also works and is cross-platform:
If you prefer to set variables directly in your shell session instead of using a file:
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.
If the first call that opens the graph database fails with:
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:
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:
  • PostgreSQL database is required if you plan to use PostgreSQL as your relational database (requires postgres extra)

​
Setup

Environment: Add your OpenAI API key to your .env file:
Installation: Install Cognee with the default package. Once your virtual environment is active, use either plain pip or uv:
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-mini for the LLM and openai/text-embedding-3-large (3072 dimensions) for embeddings.

​
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:
If you already know the stack you want, these combinations cover the most common setups:
These extras install provider SDKs. You still need to set the corresponding environment variables. See LLM Providers and Embedding Providers.
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.
If you encounter an ImportError when using a cognee feature, it usually means a required extra has not been installed.

​
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:
Releases published before the provenance pipeline landed (August 2026) carry no attestations, so verification has nothing to check for them. 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.