> ## 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? Copy the [LLM Quickstart Skill](/getting-started/llm-quickstart-skill) first 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-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

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

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

      <Tab title="venv + pip (standard)">
        ```bash theme={null}
        python -m venv .venv
        source .venv/bin/activate
        ```

        On Windows, activate with `.venv\Scripts\activate` instead of `source`.
      </Tab>
    </Tabs>
  </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, use PowerShell or Command Prompt instead of `source`:

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

        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:

        ```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>
    </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. Once your virtual environment is active, use either plain `pip` or `uv`:

      ```bash theme={null}
      # Standard pip
      pip install cognee

      # Or with uv
      uv pip install cognee
      ```

      **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-mini` 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/v1"
      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. `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]"
```

<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]"`     |
    | Distributed execution on Modal           | `uv pip install "cognee[distributed]"`   |
    | Code graph analysis                      | `uv pip install "cognee[codegraph]"`     |
    | 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]"`     |
  </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-3-5-sonnet, 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,<5`         | Use HuggingFace models for LLM or embeddings |
    | `ollama`      | `transformers>=4.46.3,<5`         | 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`   | `fastembed<=0.6.0`, `onnxruntime` | Fast local embeddings without a GPU          |

    <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                             |
    | `graphiti`        | `graphiti-core>=0.7.0,<0.8`              | Use Graphiti for temporal knowledge graphs                   |
  </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`   | `fastembed`, `transformers`, `tree-sitter`, `tree-sitter-python`                                                                | Build code graphs from Python repositories                                                              |
    | `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`         | `dlt[sqlalchemy]>=1.9.0,<2`                                                                                                     | Ingest data via DLT pipelines                                                                           |
    | `gmail`       | `dlt[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,<2` | Ingest Gmail messages into memory (read-only OAuth, incremental sync)                                   |
  </Accordion>

  <Accordion title="Infrastructure & Storage">
    | Extra         | Packages installed      | When to use                                                        |
    | ------------- | ----------------------- | ------------------------------------------------------------------ |
    | `distributed` | `modal>=1.0.5,<2.0.0`   | Run cognee pipelines on Modal for distributed/serverless execution |
    | `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]`                                 |
    | `modal`                                                                              | `cognee[distributed]`                           |
    | `playwright`, `tavily`, `beautifulsoup4`                                             | `cognee[scraping]`                              |
    | `unstructured`                                                                       | `cognee[docs]`                                  |
    | `docling`                                                                            | `cognee[docling]`                               |
    | `fastembed`                                                                          | `cognee[fastembed]` or `cognee[codegraph]`      |
    | `tree_sitter`                                                                        | `cognee[codegraph]`                             |
    | `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]`                               |
    | `graphiti`                                                                           | `cognee[graphiti]`                              |
    | `chromadb`                                                                           | `cognee[chromadb]`                              |
    | `deepeval`                                                                           | `cognee[deepeval]`                              |
    | `dlt`                                                                                | `cognee[dlt]`                                   |
    | `googleapiclient`, `google-api-python-client`, `google-auth`, `google-auth-oauthlib` | `cognee[gmail]`                                 |
  </Accordion>
</AccordionGroup>

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