> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognee.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Install Cognee and configure the basics for your first memory workflow.

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

<Info>
  Python **3.10 – 3.14** is required to run Cognee.
</Info>

<Tip>
  Using Claude Code or another LLM to set up Cognee? Install Cognee's [agent skills](/getting-started/llm-quickstart-skill) first — start with `cognee-install` — so the assistant checks Python versions, provider settings, extras, and the first smoke test in the right order.
</Tip>

## Setup Notes

<AccordionGroup>
  <Accordion title="Environment Configuration">
    * We recommend creating a `.env` file in your project root
    * Cognee supports many configuration options, and a `.env` file keeps them organized
  </Accordion>

  <Accordion title="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

    <Info>
      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.
    </Info>
  </Accordion>

  <Accordion title="Virtual Environment">
    We recommend creating a virtual environment before installing Cognee. Use whichever tool you prefer — [uv](https://github.com/astral-sh/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\`.

    <Tabs>
      <Tab title="macOS / Linux">
        ```bash theme={null}
        # uv
        uv venv
        source .venv/bin/activate

        # or standard venv + pip
        python -m venv .venv
        source .venv/bin/activate
        ```
      </Tab>

      <Tab title="Windows (PowerShell)">
        ```powershell theme={null}
        # uv
        uv venv
        .\.venv\Scripts\Activate.ps1

        # or standard venv + pip
        python -m venv .venv
        .\.venv\Scripts\Activate.ps1
        ```
      </Tab>

      <Tab title="Windows (Command Prompt)">
        ```cmd theme={null}
        :: 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.
      </Tab>
    </Tabs>

    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.
  </Accordion>

  <Accordion title="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](/setup-configuration/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.
  </Accordion>

  <Accordion title="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`:

    ```bash theme={null}
    uv add cognee
    ```

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

    ```bash theme={null}
    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.
  </Accordion>

  <Accordion title="Windows Setup">
    On Windows the setup steps differ slightly from Linux/macOS.

    <AccordionGroup>
      <Accordion title="Install uv">
        Install uv with the official standalone installer, which adds uv to your `PATH` automatically:

        <Tabs>
          <Tab title="PowerShell">
            ```powershell theme={null}
            powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
            ```
          </Tab>

          <Tab title="Command Prompt (CMD)">
            Run the PowerShell command above, or download and run the installer from [the uv installation guide](https://docs.astral.sh/uv/getting-started/installation/).
          </Tab>
        </Tabs>

        <Warning>
          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:

          ```powershell theme={null}
          python -m uv pip install cognee
          ```
        </Warning>
      </Accordion>

      <Accordion title="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`:

        <Tabs>
          <Tab title="PowerShell">
            ```powershell theme={null}
            uv venv
            .\.venv\Scripts\Activate.ps1
            ```

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

            ```powershell theme={null}
            Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
            ```
          </Tab>

          <Tab title="Command Prompt (CMD)">
            ```cmd theme={null}
            uv venv
            .venv\Scripts\activate.bat
            ```
          </Tab>
        </Tabs>
      </Accordion>

      <Accordion title="Verify the Python Interpreter">
        After installing Cognee in the [Setup](#setup) section, confirm the active interpreter can import it:

        <Tabs>
          <Tab title="PowerShell">
            ```powershell theme={null}
            python -c "import cognee; print(cognee.__file__)"
            ```
          </Tab>

          <Tab title="Command Prompt (CMD)">
            ```cmd theme={null}
            python -c "import cognee; print(cognee.__file__)"
            ```
          </Tab>
        </Tabs>

        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:

        <Tabs>
          <Tab title="PowerShell">
            ```powershell theme={null}
            Get-Command python
            ```
          </Tab>

          <Tab title="Command Prompt (CMD)">
            ```cmd theme={null}
            where python
            ```
          </Tab>
        </Tabs>

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

        <Tabs>
          <Tab title="PowerShell">
            ```powershell theme={null}
            .\.venv\Scripts\Activate.ps1
            ```
          </Tab>

          <Tab title="Command Prompt (CMD)">
            ```cmd theme={null}
            .venv\Scripts\activate.bat
            ```
          </Tab>
        </Tabs>

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

        <Tabs>
          <Tab title="PowerShell">
            ```powershell theme={null}
            .\.venv\Scripts\python.exe your_script.py
            ```
          </Tab>

          <Tab title="Command Prompt (CMD)">
            ```cmd theme={null}
            .venv\Scripts\python.exe your_script.py
            ```
          </Tab>
        </Tabs>

        In an IDE (VS Code, PyCharm), select the `.venv` interpreter as the project interpreter so the **Run** button uses it.
      </Accordion>

      <Accordion title="Configure Environment Files and Paths">
        Copy the template from the project root, then open it in any text editor (Notepad, VS Code, etc.):

        <Tabs>
          <Tab title="PowerShell">
            ```powershell theme={null}
            Copy-Item .env.template .env
            ```
          </Tab>

          <Tab title="Command Prompt (CMD)">
            ```cmd theme={null}
            copy .env.template .env
            ```
          </Tab>
        </Tabs>

        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](/setup-configuration/overview#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:

        ```ini theme={null}
        # 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:

        ```ini theme={null}
        DATA_ROOT_DIRECTORY="~/.cognee_data"
        ```

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

        <Tabs>
          <Tab title="PowerShell">
            ```powershell theme={null}
            $env:LLM_API_KEY = "your_openai_api_key"
            ```
          </Tab>

          <Tab title="Command Prompt (CMD)">
            ```cmd theme={null}
            set LLM_API_KEY=your_openai_api_key
            ```
          </Tab>
        </Tabs>

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

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

      <Accordion title="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:

        <Tabs>
          <Tab title="PowerShell">
            ```powershell theme={null}
            python --version
            ```
          </Tab>

          <Tab title="Command Prompt (CMD)">
            ```cmd theme={null}
            python --version
            ```
          </Tab>
        </Tabs>

        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:

        <Tabs>
          <Tab title="PowerShell">
            ```powershell theme={null}
            uv venv --python 3.12
            .\.venv\Scripts\Activate.ps1
            uv pip install cognee
            ```
          </Tab>

          <Tab title="Command Prompt (CMD)">
            ```cmd theme={null}
            uv venv --python 3.12
            .venv\Scripts\activate.bat
            uv pip install cognee
            ```
          </Tab>
        </Tabs>
      </Accordion>
    </AccordionGroup>
  </Accordion>

  <Accordion title="Optional">
    <AccordionGroup>
      <Accordion title="Database">
        * PostgreSQL database is required if you plan to use PostgreSQL as your relational database (requires `postgres` extra)
      </Accordion>
    </AccordionGroup>
  </Accordion>
</AccordionGroup>

## Setup

<Tabs>
  <Tab title="OpenAI (Recommended)">
    <Card>
      **Environment:** Add your OpenAI API key to your `.env` file:

      ```bash theme={null}
      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:

      <CodeGroup>
        ```bash pip theme={null}
        pip install cognee
        ```

        ```bash uv virtual environment theme={null}
        uv pip install cognee
        ```

        ```bash uv project (pyproject.toml) theme={null}
        uv add cognee
        ```
      </CodeGroup>

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

      <Info>
        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.
      </Info>
    </Card>
  </Tab>

  <Tab title="Other Providers (Gemini, Anthropic, etc.)">
    <Card>
      **Environment:** Configure both LLM and embedding providers in your `.env` file. Here is an example for Gemini:

      ```bash theme={null}
      # 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"
      ```

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

      **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](/setup-configuration/llm-providers) and [Embeddings](/setup-configuration/embedding-providers) guides.
    </Card>
  </Tab>

  <Tab title="Ollama (Local, No API Key)">
    <Card>
      **Environment:** Run both the LLM and embeddings locally with [Ollama](https://ollama.ai). 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:

      ```bash theme={null}
      # 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](/setup-configuration/llm-providers#ollama-local)). `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:

      ```bash theme={null}
      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.

      <Info>
        Configure **both** LLM and embeddings to a local backend. If you set only one, the other defaults to OpenAI. See the [Local Setup guide](/guides/local-setup) for an Ollama LLM + Fastembed alternative and troubleshooting.
      </Info>
    </Card>
  </Tab>
</Tabs>

## 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:

```bash theme={null}
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).

<AccordionGroup>
  <Accordion title="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]"` |
  </Accordion>

  <Accordion title="LLM & Embedding Providers">
    These extras install provider SDKs. You still need to set the corresponding environment variables. See [LLM Providers](/setup-configuration/llm-providers) and [Embedding Providers](/setup-configuration/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](/python-api/cognify#installing-the-runtime) |

    <Info>
      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`.
    </Info>
  </Accordion>

  <Accordion title="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 |
  </Accordion>

  <Accordion title="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](/integrations/dlt-integration#gmail-connector) or the [Gmail integration](/integrations/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](/integrations/google-drive-integration) (from `v1.6.1`) |
  </Accordion>

  <Accordion title="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 |
  </Accordion>

  <Accordion title="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 |
  </Accordion>

  <Accordion title="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 |
  </Accordion>

  <Accordion title="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 |
  </Accordion>

  <Accordion title="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](/guides/gliner-llm-free-cognify)), 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]` |
  </Accordion>
</AccordionGroup>

## 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](https://pypi.org/project/cognee/), plus a GitHub-hosted SLSA build provenance attestation. To confirm a downloaded wheel or sdist was built by CI from `topoteretes/cognee`:

```bash theme={null}
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`](https://pypi.org/project/cognee/) | `v<version>` | The library. Weekly canaries are versioned `X.Y.Z.devYYYYMMDD` and are not tagged |
| [`cognee-mcp`](https://pypi.org/project/cognee-mcp/) | `cognee-mcp-v<version>` | The [MCP server](/cognee-mcp/mcp-overview). 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:

```bash theme={null}
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](https://github.com/topoteretes/cognee/releases) 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:

```bash theme={null}
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](https://github.com/topoteretes/cognee/blob/dev/docs/supply_chain_provenance.md) in the cognee repo.

## Next Steps

<CardGroup cols={2}>
  <Card title="Run Your First Example" href="/getting-started/quickstart" icon="play">
    **Quickstart Tutorial**

    Get started with Cognee by running your first knowledge graph example.
  </Card>

  <Card title="Explore Advanced Features" href="/core-concepts" icon="compass">
    **Core Concepts**

    Dive deeper into Cognee's powerful features and capabilities.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.