LightRAG

1.4.15 verified Mon Apr 27 auth: no python

LightRAG is a simple and fast retrieval-augmented generation (RAG) framework that supports graph-based knowledge retrieval. The current stable version is 1.4.15, with a release candidate 1.5.0rc1 introducing breaking changes. Releases are frequent (weekly/monthly).

pip install lightrag-hku

Common errors

error RuntimeError: asyncio.run() cannot be called from a running event loop ↓

cause Calling async function from an already running event loop (e.g., in Jupyter or another async context).

fix

Use await directly if inside an async function, or use nest_asyncio.apply() in Jupyter.

error ModuleNotFoundError: No module named 'lightrag' ↓

cause Installed wrong package name 'lightrag' instead of 'lightrag-hku'.

fix

Run: pip install lightrag-hku

error KeyError: 'OPENAI_API_KEY' ↓

cause Environment variable for OpenAI API key not set.

fix

Set the OPENAI_API_KEY environment variable or pass it via LLM configuration.

error AttributeError: 'LightRAG' object has no attribute 'insert' ↓

cause User called synchronous method incorrectly; LightRAG methods are async.

fix

Use await on async methods: await rag.ainsert('...') instead of rag.insert('...').

Warnings

breaking In v1.5.0rc1, the ENTITY_TYPES environment variable has been deprecated. Replace it with ENTITY_TYPE_PROMPT_FILE before launching. ↓

fix Set ENTITY_TYPE_PROMPT_FILE instead of ENTITY_TYPES in your environment or .env file.

breaking In v1.5.0rc1, LLM configuration roles have been restructured into four distinct roles: EXTRACT, QUERY, KEYWORDS, and VLM. Existing single LLM configs will break. ↓

fix Provide separate LLM configurations for each role (e.g., EXTRACT_LLM_MODEL, QUERY_LLM_MODEL) or use the new role-specific settings.

gotcha LightRAG uses async by default. Synchronous wrappers (e.g., insert, query) require the event loop to be running. Calling sync methods outside an async context may cause 'RuntimeError: asyncio.run() cannot be called from a running event loop'. ↓

fix Use async methods (ainsert, aquery, etc.) with asyncio.run() or run the sync methods inside a running event loop.

gotcha Working directory must be writable; LightRAG stores index files and databases there. If the directory does not exist, it will be created, but permissions issues may cause silent failures. ↓

fix Ensure the working directory exists and is writable, or use an absolute path that the application has permission to write to.

Imports

LightRAG
wrong
```
import lightrag
```
correct
```
from lightrag import LightRAG
```
LightRAG class is not a top-level module
QueryParam
```
from lightrag import QueryParam
```
No common wrong import

Quickstart

Initialize LightRAG with OpenAI LLM and embedding, insert a document, and query.

import asyncio
from lightrag import LightRAG, QueryParam
from lightrag.llm import openai_complete_if_cache, openai_embedding

async def main():
    rag = LightRAG(
        working_dir='./rag_storage',
        llm_model_func=openai_complete_if_cache,
        embedding_func=openai_embedding,
    )
    # Insert a document
    await rag.ainsert('LightRAG is a RAG framework.')
    # Query
    result = await rag.aquery('What is LightRAG?', param=QueryParam(mode='hybrid'))
    print(result)

asyncio.run(main())