Installing llama-index and required packages
Why this matters
You cannot build anything with llama-index until the packages are installed correctly. A misconfigured environment causes cryptic import errors that waste debugging time. Getting this right the first time unblocks every subsequent lesson.
Explanation
llama-index-core is the foundational package for building retrieval-augmented generation (RAG) applications. It provides vector stores, document loaders, and LLM integrations. When you install it, you get the core framework, but you need additional packages for specific integrations: OpenAI for GPT models, Pinecone for vector storage, or Ollama for local LLMs. How it works mechanically: pip fetches the packages from PyPI, resolves their dependencies (including transitive ones like pydantic, httpx, nest-asyncio), and installs them into your Python environment's site-packages directory. Version conflicts between dependencies can cause silent failures where imports succeed but behavior is broken. When to use this approach: Always start here before your first llama-index project. Use a virtual environment (venv or conda) to isolate packages per project: never install globally into your system Python.
Analogy
Installing packages is like setting up a construction site. llama-index-core is the main toolbox, but you also need specialized tool kits (OpenAI wrench, Pinecone measuring tape). If you don't install the right tools, your blueprints won't execute. A virtual environment is your isolated job site so one project's tools don't interfere with another's.
Code
#!/usr/bin/env python3
import subprocess
import sys
import json
packages_to_install = [
'llama-index-core>=0.12.0',
'llama-index-llms-openai>=0.1.0',
]
print('Installing llama-index packages...')
for package in packages_to_install:
result = subprocess.run(
[sys.executable, '-m', 'pip', 'install', package],
capture_output=True,
text=True
)
if result.returncode == 0:
print(f'✓ Successfully installed {package}')
else:
print(f'✗ Failed to install {package}')
print(f'Error: {result.stderr}')
sys.exit(1)
print('\nVerifying installation...')
try:
from llama_index.core import VectorStoreIndex, SimpleDirectoryReader, Settings
from llama_index.llms.openai import OpenAI
print('✓ llama-index-core imports successful')
print('✓ OpenAI integration imports successful')
print(f'\nllama-index-core version: {__import__("llama_index.core").__version__}')
except ImportError as e:
print(f'✗ Import failed: {e}')
sys.exit(1)
print('\n✓ All packages installed and verified successfully!')Installing llama-index packages... ✓ Successfully installed llama-index-core>=0.12.0 ✓ Successfully installed llama-index-llms-openai>=0.1.0 Verifying installation... ✓ llama-index-core imports successful ✓ OpenAI integration imports successful llama-index-core version: 0.12.8 ✓ All packages installed and verified successfully!
What just happened?
The code used pip to install two packages: the core llama-index framework and the OpenAI integration. After installation, it imported the key modules to verify they're accessible. The version check confirms that a compatible version of llama-index-core is installed. If any step failed, the script exits with an error code so you can see exactly where the installation broke.
Common gotcha
Many developers install llama-index (the old 0.1.x package) instead of llama-index-core. The old package is deprecated and incompatible with modern code. You'll get confusing import errors like ModuleNotFoundError: No module named 'llama_index.core' because the old package has a different structure. Always install llama-index-core, not llama-index.
Error recovery
ModuleNotFoundError: No module named 'llama_index.core'pip: command not founderror: ERROR: Could not find a version that satisfies the requirementPermissionError: [Errno 13] Permission deniedExperienced dev note
Always use a virtual environment: never skip this step, even for 'quick' projects. A version conflict from a previous project can silently break new code. The pattern `[sys.executable, '-m', 'pip', 'install', ...]` is more reliable than calling `pip` directly because it uses the correct Python interpreter. If you're on a team, add a `requirements.txt` with pinned versions (e.g., `llama-index-core==0.12.8`) so everyone runs the exact same code. The difference between `>=0.12.0` (any version 0.12 or newer) and `==0.12.8` (only this version) matters in production: use pinned versions in requirements.txt, flexible versions only during exploration.
Check your understanding
You just installed llama-index-core successfully and verified the import. Now, if a colleague asks 'Why can't I import llama_index.core after running pip install llama-index?' what is the most likely reason, and what's the exact fix?
Show answer hint
A correct answer identifies that they installed the deprecated `llama-index` package (the old 0.1.x version) instead of `llama-index-core`, and the fix is to uninstall the wrong package and install the correct one. Simply running pip install again won't work: the old package has to be removed first.