Loaders

​

Loader Selection

1. CodeLoader: For source-code files (.py, .ts, .go, .rs, etc.). It sits ahead of TextLoader because code content-sniffs as plain text, so TextLoader would otherwise claim it first.
2. TextLoader: For plain text files (.txt, .md, .json, .xml, etc.).
3. PyPdfLoader: For PDF files (requires pypdf).
4. ImageLoader: For images (uses vision models to transcribe content, with an optional local OCR pass).
5. AudioLoader: For audio files (uses transcription models).
6. VideoLoader: For video files (transcribes the audio track with inline [HH:MM:SS] timestamps).
7. DltCsvLoader: For CSV files (routes rows through dlt structured ingestion instead of text). It sits above CsvLoader, so this is the default route for every .csv.
8. CsvLoader: For CSV files (converts rows to text).
9. UnstructuredLoader: For complex formats like .docx, .pptx, .epub (requires unstructured).
10. AdvancedPdfLoader: For layout-aware PDF extraction (requires unstructured).
11. DoclingLoader: If no other loader can ingest the file type, Docling is used for conversion (if the type is supported).

​

Available Loaders

​

Core Loaders

• CodeLoader: Claims source-code files by file-name extension and stores them verbatim under their original extension. Files it claims take the deterministic code graph pipeline during cognify() instead of LLM-based extraction. See the “Code Loader” accordion below.
• TextLoader: Reads text files with UTF-8 encoding. It is also the content-detection fallback, so a file whose bytes sniff as plain text but are not decodable is refused with a typed error rather than an internal failure — see the note below.
• DltCsvLoader: Ingests .csv files through the dlt structured path instead of flattening them to text — the rows are loaded into a dlt staging database and the loader emits one manifest per CSV file, which cognify turns into row nodes deterministically from the schema, with no LLM extraction. dlt is a core cognee dependency, so this loader registers on every install and, sitting above CsvLoader in the priority order, claims every CSV by default.
• CsvLoader: Reads CSV files and converts each row into a structured text format (Row N: key: value). Because DltCsvLoader outranks it, this loader is reached only when you ask for it per call with preferred_loaders=[{"csv_loader": {}}].
• ImageLoader: Uses an LLM vision model to transcribe the image content. By default the transcription uses an extraction-oriented prompt that asks for entities, relationships, verbatim text, and structured content (tables, charts, diagrams) rather than a short caption. An optional local OCR pass can be enabled to append recognized text to the transcription; it requires pip install cognee[rapidocr]. See the “Image transcription and OCR” accordion below.
• AudioLoader: Uses an audio transcription API to transcribe audio files. This depends on your configured LLM provider supporting transcription endpoints; see LLM Providers for provider-specific caveats.
• VideoLoader: Transcribes a video’s audio track into text with inline [HH:MM:SS] segment timestamps, then feeds it through the normal text pipeline. .mp4 and .webm do not require ffmpeg; other containers do (see the VideoLoader usage accordion below).

Image ingestion needs an LLM: cognee describes images with a vision model before
indexing them, and no LLM API key is configured. Set LLM_API_KEY to ingest this
file. Text, document and code files need no key — cognee processes those with
local models.

'Installer.dmg' cannot be read as text: decoding it as utf-8 failed (invalid
continuation byte at byte 1). Its content was detected as plain text, but the
bytes are binary, so no cognee loader can read this file. Supported text
extensions: txt, md, json, xml, yaml, yml, log; PDFs and office documents need
their own loader (the `docling` extra).

​

External Loaders

• PyPdfLoader: Extracts text from PDFs page by page using the pypdf library, preserving page boundaries with Page N: markers in the extracted text. Requires pip install cognee[docs] (or pip install pypdf).
• AdvancedPdfLoader: Layout-aware PDF extraction using the unstructured library. Extracts text, tables (as HTML), and image placeholders per page. Falls back to PyPdfLoader automatically if extraction fails. Requires pip install cognee[docs], plus poppler and tesseract installed on the system.
• UnstructuredLoader: Handles many office and document formats (.docx, .xlsx, .pptx, .odt, .rtf, .eml, .epub, .html, and more) via unstructured’s auto-partition. Requires pip install cognee[docs].
• BeautifulSoupLoader: Extracts text from HTML files using BeautifulSoup. Applies CSS selector rules to pull structured content from specific tags. Requires pip install cognee[scraping].
• DoclingLoader: Catch-all fallback that converts a wide range of document formats (PDF, DOCX, XLSX, PPTX, HTML, Markdown, and more) to plain text via Docling. Supported extensions are discovered dynamically from Docling’s FormatToExtensions map. Requires pip install cognee[docling].

​

Supported File Extensions

​

Usage

import cognee

await cognee.remember(
    data=["example_website.html"],
    preferred_loaders=[
        {
            "beautiful_soup_loader": {
                "extraction_rules": {
                    "title": "h1",
                    "body": "article.main-content"
                }
            }
        }
    ]
)

await cognee.remember(
    data=["employees.csv"],
    preferred_loaders=[{"csv_loader": {}}]
)

await cognee.remember(
    data=["employees.csv"],
    preferred_loaders=[
        {"dlt_csv_loader": {"primary_key": "id", "write_disposition": "merge"}}
    ]
)

import cognee

await cognee.remember(data=["src/service.py"])

import cognee

await cognee.remember(
    data=["src/service.py"],
    preferred_loaders=[{"text_loader": {}}]
)

# .env
ENOLA_PATH="/opt/enola/enola"

import cognee

await cognee.remember(
    data=["scanned_document.pdf"],
    preferred_loaders=[
        {"advanced_pdf_loader": {"strategy": "ocr_only"}}
    ]
)

# Japanese
sudo apt-get install tesseract-ocr-jpn tesseract-ocr-jpn-vert

# Chinese (Simplified / Traditional)
sudo apt-get install tesseract-ocr-chi-sim tesseract-ocr-chi-tra

# Korean
sudo apt-get install tesseract-ocr-kor

import cognee

# Japanese PDF
await cognee.remember(
    data=["japanese_document.pdf"],
    preferred_loaders=[
        {
            "advanced_pdf_loader": {
                "strategy": "ocr_only",
                "languages": ["jpn"]
            }
        }
    ]
)

import cognee

await cognee.remember(
    data=["presentation.pptx"],
    preferred_loaders=[
        {
            "unstructured_loader": {
                "strategy": "fast"
            }
        }
    ]
)

import cognee

await cognee.remember(
    data=["report.pdf"],
    preferred_loaders=[{"docling_loader": {}}]
)

import cognee

await cognee.remember(
    data=["page.html"],
    preferred_loaders=[
        {
            "beautiful_soup_loader": {
                "extraction_rules": {
                    "title": {"selector": "h1", "all": False},
                    "body": {"selector": "article.main-content", "all": True, "join_with": "\n\n"},
                    "og_image": {"selector": "meta[property='og:image']", "attr": "content"}
                }
            }
        }
    ]
)

await cognee.remember(
    data=["page.html"],
    preferred_loaders=[
        {
            "beautiful_soup_loader": {
                "extraction_rules": {
                    "content": {"xpath": "//div[@class='content']//p"}
                }
            }
        }
    ]
)

# .env — enable vision by choosing a vision-capable model
LLM_PROVIDER="openai"
LLM_MODEL="gpt-4o-mini"
LLM_API_KEY="sk-..."

# Optional: a dedicated vision model for images only
# IMAGE_TRANSCRIBE_MODEL="gpt-4o"

# .env — restore the previous short-caption behavior
IMAGE_EXTRACTION_ENABLED="false"

A bar chart titled "Quarterly revenue" with four bars...

[OCR extracted text]
Quarterly revenue
Q1 1.2M
Q2 1.8M

pip install cognee[rapidocr]

# .env
IMAGE_OCR_ENABLED="true"

# .env
IMAGE_TRANSCRIPTION_PROMPT_PATH="/etc/cognee/prompts/my_image_prompt.txt"

[00:00:00] Welcome to the walkthrough.
[00:00:12] First we configure the environment.

import cognee

await cognee.remember(data=["walkthrough.mp4"])

from cognee.infrastructure.loaders import use_loader
from cognee.infrastructure.loaders.LoaderInterface import LoaderInterface

class MyCustomLoader(LoaderInterface):
    loader_name = "my_custom_loader"
    supported_extensions = ["custom"]
    supported_mime_types = ["application/x-custom"]

    async def load(self, file_path, **kwargs):
        # Your custom logic to read the file and return text
        return "Extracted text content"

# Register the loader so Cognee can use it
use_loader("my_custom_loader", MyCustomLoader)

await cognee.remember("data/file.custom")

from cognee.infrastructure.loaders.LoaderInterface import LoaderInterface, LoaderResult

class MyCustomLoader(LoaderInterface):
    ...
    async def load(self, file_path, **kwargs):
        return LoaderResult(
            file_path=stored_text_path,   # required: the derived-text path
            data_id=my_stable_uuid,       # optional: pins the record's id
            system_metadata={...},        # optional: routing stamp for cognify
        )