{"id":21526,"library":"lightrag-hku","title":"LightRAG","description":"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).","status":"active","version":"1.4.15","language":"python","source_language":"en","source_url":"https://github.com/HKUDS/LightRAG","tags":["rag","retrieval-augmented-generation","graph-rag","llm","embeddings"],"install":[{"cmd":"pip install lightrag-hku","lang":"bash","label":"Install from PyPI"}],"dependencies":[{"reason":"Numerical operations and embeddings","package":"numpy","optional":false},{"reason":"Default LLM and embedding provider","package":"openai","optional":true},{"reason":"Async HTTP requests","package":"aiohttp","optional":false}],"imports":[{"note":"LightRAG class is not a top-level module","wrong":"import lightrag","symbol":"LightRAG","correct":"from lightrag import LightRAG"},{"note":"No common wrong import","symbol":"QueryParam","correct":"from lightrag import QueryParam"}],"quickstart":{"code":"import asyncio\nfrom lightrag import LightRAG, QueryParam\nfrom lightrag.llm import openai_complete_if_cache, openai_embedding\n\nasync def main():\n    rag = LightRAG(\n        working_dir='./rag_storage',\n        llm_model_func=openai_complete_if_cache,\n        embedding_func=openai_embedding,\n    )\n    # Insert a document\n    await rag.ainsert('LightRAG is a RAG framework.')\n    # Query\n    result = await rag.aquery('What is LightRAG?', param=QueryParam(mode='hybrid'))\n    print(result)\n\nasyncio.run(main())","lang":"python","description":"Initialize LightRAG with OpenAI LLM and embedding, insert a document, and query."},"warnings":[{"fix":"Set ENTITY_TYPE_PROMPT_FILE instead of ENTITY_TYPES in your environment or .env file.","message":"In v1.5.0rc1, the ENTITY_TYPES environment variable has been deprecated. Replace it with ENTITY_TYPE_PROMPT_FILE before launching.","severity":"breaking","affected_versions":">=1.5.0rc1"},{"fix":"Provide separate LLM configurations for each role (e.g., EXTRACT_LLM_MODEL, QUERY_LLM_MODEL) or use the new role-specific settings.","message":"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.","severity":"breaking","affected_versions":">=1.5.0rc1"},{"fix":"Use async methods (ainsert, aquery, etc.) with asyncio.run() or run the sync methods inside a running event loop.","message":"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'.","severity":"gotcha","affected_versions":"all"},{"fix":"Ensure the working directory exists and is writable, or use an absolute path that the application has permission to write to.","message":"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.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Use await directly if inside an async function, or use nest_asyncio.apply() in Jupyter.","cause":"Calling async function from an already running event loop (e.g., in Jupyter or another async context).","error":"RuntimeError: asyncio.run() cannot be called from a running event loop"},{"fix":"Run: pip install lightrag-hku","cause":"Installed wrong package name 'lightrag' instead of 'lightrag-hku'.","error":"ModuleNotFoundError: No module named 'lightrag'"},{"fix":"Set the OPENAI_API_KEY environment variable or pass it via LLM configuration.","cause":"Environment variable for OpenAI API key not set.","error":"KeyError: 'OPENAI_API_KEY'"},{"fix":"Use await on async methods: await rag.ainsert('...') instead of rag.insert('...').","cause":"User called synchronous method incorrectly; LightRAG methods are async.","error":"AttributeError: 'LightRAG' object has no attribute 'insert'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}