Install & Compatibility
Where this runs
tested against v0.14.24 · 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
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 4.229s · 258.9MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 19.7s · import 3.939s · 255MB
270MB installed
● package 270MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
VectorStoreIndex
✓ from llama_index.core import VectorStoreIndex
SimpleDirectoryReader
✓ from llama_index.core.readers import SimpleDirectoryReader
Settings
✓ from llama_index.core import Settings
✗ from llama_index.core import ServiceContext
ServiceContext was deprecated and largely replaced by the global Settings object or explicit passing of components.
OpenAI
✓ from llama_index.llms.openai import OpenAI
OpenAIEmbedding
✓ from llama_index.embeddings.openai import OpenAIEmbedding
This quickstart demonstrates loading data, configuring the LLM and embedding model via global `Settings`, creating a vector store index, and performing a simple query. Ensure you have the `OPENAI_API_KEY` environment variable set and the `llama-index-llms-openai` and `llama-index-embeddings-openai` packages installed.
import os
from llama_index.core import VectorStoreIndex, SimpleDirectoryReader, Settings
from llama_index.llms.openai import OpenAI
from llama_index.embeddings.openai import OpenAIEmbedding
# Ensure you have your OpenAI API key set as an environment variable
# os.environ["OPENAI_API_KEY"] = "sk-..."
OPENAI_API_KEY = os.environ.get('OPENAI_API_KEY', '')
if not OPENAI_API_KEY:
raise ValueError("OPENAI_API_KEY environment variable not set.")
# Create a dummy data directory and file
if not os.path.exists("data"):
os.makedirs("data")
with open("data/hello.txt", "w") as f:
f.write("The quick brown fox jumps over the lazy dog.\n")
f.write("LlamaIndex is a data framework for LLM applications.")
# 1. Load data
documents = SimpleDirectoryReader("data").load_data()
# 2. Configure global settings (LLM and Embedding Model)
Settings.llm = OpenAI(api_key=OPENAI_API_KEY, model="gpt-3.5-turbo")
Settings.embed_model = OpenAIEmbedding(api_key=OPENAI_API_KEY, model="text-embedding-ada-002")
# 3. Create an index
index = VectorStoreIndex.from_documents(documents)
# 4. Create a query engine
query_engine = index.as_query_engine()
# 5. Query the index
response = query_engine.query("What is LlamaIndex?")
print(response.response)
Debug
Known issues
breakingMajor architectural shift to a modular package structure in versions ~0.10.x and onwards. Core functionalities moved to `llama-index-core`, and all LLM, embedding, vector store, etc., integrations became separate packages (e.g., `llama-index-llms-openai`, `llama-index-embeddings-openai`).fixMigrate imports and installations to use `llama-index-core` for base classes and explicitly install `llama-index-<component>-<integration_name>` packages for specific integrations. Update import paths from `llama_index.<component>.<integration>` to `llama_index.<component>.<integration>` (e.g., `from llama_index.llms.openai import OpenAI`).
affects: >=0.10.0
breakingThe `ServiceContext` class was deprecated and largely replaced by the global `Settings` object for configuration. While `ServiceContext` might still exist in some forms, `Settings` is the recommended way to configure LLMs, embedding models, chunk sizes, etc.fixReplace `ServiceContext.from_defaults(...)` with direct assignments to `Settings.llm`, `Settings.embed_model`, `Settings.chunk_size`, etc. Explicitly pass components where granular control is needed.
affects: >=0.10.0
deprecatedSupport for Python 3.9 has been officially deprecated and removed.fixUpgrade your Python environment to 3.10 or higher. The library currently targets `<4.0,>=3.10`.
affects: >=0.14.18
gotchaMany LlamaIndex components (LLMs, embeddings, vector stores, data loaders) default to using `openai` if not explicitly configured. This often leads to `openai` being a de-facto dependency for basic usage, requiring an API key even if not intended.fixAlways explicitly configure your desired LLM and embedding model via `Settings.llm` and `Settings.embed_model` or by passing them directly to constructors. Ensure relevant integration packages are installed (e.g., `llama-index-llms-anthropic`, `llama-index-embeddings-huggingface`).
affects: All versions
gotchaWhen migrating from older versions, `Document` and `Node` structures might have subtle differences in metadata handling and content fields. For instance, `text` vs `content` or `extra_info` vs `metadata`.fixConsult the migration guides in the official LlamaIndex documentation when upgrading across major architectural changes. Pay close attention to how document content and metadata are accessed and stored.
affects: Pre-0.10.x to Post-0.10.x migrations
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'llama_index.query_engine'
With the modularization of LlamaIndex, many core components and integrations were moved into the `llama-index-core` package or separate integration packages. Users often forget to adjust their imports to include `.core` or install the specific integration package.
fixChange the import statement to `from llama_index.core.query_engine import ...` or `from llama_index.core.text_splitter import SentenceSplitter` (or the respective module within `llama_index.core`). If it's an integration, ensure the specific integration package (e.g., `llama-index-llms-openai`) is installed and imported correctly, often still under `llama_index.llms.openai` namespace.
ModuleNotFoundError: No module named 'llama_index'
This error typically occurs when a user expects the monolithic `llama_index` package to be installed, but has instead installed the modular `llama-index-core` package (and potentially other specific integration packages) without the `llama_index` meta-package, leading to a missing top-level `llama_index` module.
fixInstall the main `llama-index` meta-package using `pip install llama-index` which includes `llama-index-core` and a minimal set of common integrations, or explicitly install `llama-index-core` and all necessary integration packages (e.g., `pip install llama-index-core llama-index-llms-openai`).
AttributeError: module 'llama_index.core' has no attribute '__version__'
Users attempting to access `__version__` directly on `llama_index.core` may encounter this if the attribute's location or availability has changed, or if there's a conflict in the environment after updates.
fixThe `__version__` attribute might be available directly on the `llama_index` package (if installed) or within other internal modules. A reliable way to check the installed version is `pip show llama-index` or `pip show llama-index-core`.
DeprecationWarning: ServiceContext is deprecated, use Settings instead.
The `ServiceContext` object has been deprecated in `llama-index-core` in favor of a more streamlined `Settings` object, which directly manages LLMs, embeddings, and other configurations. Using the old `ServiceContext` will trigger this warning.
fixRefactor your code to use the `Settings` object for configuring LLMs, embedding models, and other service parameters. For example, instead of `service_context = ServiceContext.from_defaults(llm=my_llm)`, use `from llama_index.core import Settings; Settings.llm = my_llm`.
ImportError: cannot import name 'LLM' from 'llama_index.core.llms'
This error occurs when a specific class or object, like 'LLM', is expected to be directly importable from a module within `llama_index.core` but its path or export status has changed due to API updates and refactoring.
fixVerify the correct import path for the desired class in the latest `llama-index-core` documentation or changelog. Often, base classes like `LLM` are now part of `llama_index.core.llms.llm` or similar specific files, and integration-specific LLMs are in their own packages (e.g., `from llama_index.llms.openai import OpenAI`).
Upgrade
Version history
0.14.24latest on PyPI · released Aug 19, 2026
Audit
Dependencies
pythonrequiredRequires Python 3.10 or higher, less than 4.0.