Implementation:Run llama Llama index Upgrade Tool

Knowledge Sources	Run_llama_Llama_index
Domains	LLM Framework, Migration, CLI
Last Updated	2026-02-11 19:00 GMT

Overview

This module provides an import migration tool that automatically upgrades LlamaIndex import statements from the legacy monolithic package structure to the new modular package structure introduced in the v0.10+ refactor.

Description

The upgrade tool processes Python files (.py), Markdown files (.md), and Jupyter notebooks (.ipynb) to rewrite import statements. It reads a mappings.json file that maps module names to their new package locations.

Core parsing functions:

• _parse_from_imports(mappings, installed_modules, line_idx, lines, verbose) -- Parses from ... import ... statements, including multi-line imports with parentheses. For each imported symbol, it looks up the new package location in the mappings dictionary. If a symbol is not found in the mappings, it falls back to replacing llama_index with llama_index.core in the import path. Returns new import lines, new pip install statements, updated installed modules list, and the number of lines consumed.

• _parse_hub_downloads(mappings, installed_modules, line) -- Handles download_loader() and download_tool() calls from the legacy llama_hub pattern. Uses a regex to extract the module name, looks it up in mappings, and generates the appropriate from ... import ... statement.

• parse_lines(lines, installed_modules, verbose) -- The main parsing orchestrator. Iterates through all lines, detecting from llama_index. imports, from llama_hub. imports, and hub download calls, delegating to the appropriate parser. Returns the rewritten lines and a deduplicated list of new pip install statements.

Notebook-specific functions:

• _cell_installs_llama_hub(cell) -- Detects notebook cells that install llama-hub or import download utilities, so they can be removed.
• _format_new_installs(new_installs) -- Formats install statements for notebook cells, removing trailing newlines from the last entry.
• upgrade_nb_file(file_path) -- Processes a Jupyter notebook: rewrites imports in all code cells, inserts a new cell with pip install commands at the top, and removes legacy llama-hub installation cells.

File-level functions:

• upgrade_py_md_file(file_path) -- Processes a .py or .md file: reads all lines, rewrites imports, writes the file back, and prints any new required pip installs.
• upgrade_file(file_path) -- Dispatcher that routes to upgrade_nb_file or upgrade_py_md_file based on file extension.
• _is_hidden(path) -- Checks if a file path contains hidden directory components (starting with .).
• upgrade_dir(input_dir) -- Recursively finds all .py, .ipynb, and .md files in a directory (excluding hidden paths) and upgrades each one.

Usage

Use this tool when migrating a codebase from the legacy LlamaIndex monolithic package to the new modular package structure. It can be run on individual files or entire directories via the command line.

Code Reference

Source Location

• Repository: Run_llama_Llama_index
• File: llama-index-core/llama_index/core/command_line/upgrade.py
• Lines: 1-286

Signature

def _parse_from_imports(
    mappings: Dict[str, str],
    installed_modules: List[str],
    line_idx: int,
    lines: List[str],
    verbose: bool = False,
) -> Tuple[List[str], List[str], List[str], int]: ...

def _parse_hub_downloads(
    mappings: Dict[str, str],
    installed_modules: List[str],
    line: str,
) -> Tuple[List[str], List[str], List[str]]: ...

def parse_lines(
    lines: List[str], installed_modules: List[str], verbose: bool = False
) -> Tuple[List[str], List[str]]: ...

def upgrade_nb_file(file_path: str) -> None: ...
def upgrade_py_md_file(file_path: str) -> None: ...
def upgrade_file(file_path: str) -> None: ...
def upgrade_dir(input_dir: str) -> None: ...

Import

from llama_index.core.command_line.upgrade import (
    upgrade_file,
    upgrade_dir,
    upgrade_py_md_file,
    upgrade_nb_file,
    parse_lines,
)

I/O Contract

Inputs

Name	Type	Required	Description
file_path	str	Yes (for file functions)	Path to the file to upgrade (.py, .md, or .ipynb).
input_dir	str	Yes (for upgrade_dir)	Path to the directory to recursively upgrade.
lines	List[str]	Yes (for parse_lines)	List of source code lines to process.
installed_modules	List[str]	Yes (for parse_lines)	List of already-installed module names (pip package format) to avoid duplicate install suggestions.
mappings	Dict[str, str]	Yes (for internal parsers)	Dictionary mapping old symbol names to new import paths, loaded from mappings.json.
verbose	bool	No	Enables verbose output during parsing. Defaults to False.

Outputs

Name	Type	Description
return (parse_lines)	Tuple[List[str], List[str]]	A tuple of (rewritten lines, list of new pip install commands).
return (upgrade_file, upgrade_dir)	None	Files are modified in-place; new install requirements are printed to stdout.

Usage Examples

Basic Usage

from llama_index.core.command_line.upgrade import upgrade_file, upgrade_dir

# Upgrade a single Python file
upgrade_file("my_project/main.py")

# Upgrade a single Jupyter notebook
upgrade_file("notebooks/rag_example.ipynb")

# Upgrade all files in a directory recursively
upgrade_dir("my_project/")

Programmatic Line Parsing

from llama_index.core.command_line.upgrade import parse_lines

lines = [
    "from llama_index import VectorStoreIndex, SimpleDirectoryReader\n",
    "from llama_index import ServiceContext\n",
]

new_lines, new_installs = parse_lines(lines, installed_modules=["llama-index-core"])
print("Rewritten imports:")
for line in new_lines:
    print(line, end="")
print("\nNew installs needed:")
for install in new_installs:
    print(install.strip())

Related Pages

• Environment:Run_llama_Llama_index_Python_LlamaIndex_Core