lightrag-hku

library1.5.3pypypi✓ verified 85d ago

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

llm-agents ai-ml database

pip install lightrag-hku

github ↗package ↗docs ↗

INSTALL

IMPORT

SIG · LIGHTRAG-HKU

lightrag-hku

llm-agentspythonv1.5.3

Install

19.0s avg

Import

1776ms

Disk

283MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.5.3 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 1.814s · 279.2MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 19.0s · import 1.738s · 274MB

283MB installed

● package 283MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

LightRAG

✓ from lightrag import LightRAG

✗ import lightrag

LightRAG class is not a top-level module

QueryParam

✓ from lightrag import QueryParam

No common wrong import

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

Debug

Known issues

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

affects: >=1.5.0rc1

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

affects: >=1.5.0rc1

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

affects: all

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

affects: all

Errors

Common errors & fixes

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

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.

ModuleNotFoundError: No module named 'lightrag'

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

fix

Run: pip install lightrag-hku

KeyError: 'OPENAI_API_KEY'

Environment variable for OpenAI API key not set.

fix

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

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

User called synchronous method incorrectly; LightRAG methods are async.

fix

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

Upgrade

Version history

1.5.3latest on PyPI · released Jun 14, 2026

Audit

Dependencies

numpyrequiredNumerical operations and embeddings

openaioptionalDefault LLM and embedding provider

aiohttprequiredAsync HTTP requests

Agent activity

30 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/HKUDS/LightRAG ↗

packagehttps://pypi.org/project/lightrag-hku/ ↗

docshttps://github.com/HKUDS/LightRAG ↗