How do we migrate from the deprecated llama-parse package to the llama-cloud SDK for LlamaIndex?

Most teams hit this migration path the same way: you’ve got working code using the deprecated llama-parse package, and now you’re being asked to move to the Llama Cloud SDK without breaking your document pipelines. The good news: the new SDK gives you more control, better alignment with the rest of the LlamaIndex stack, and a cleaner upgrade path for future features.

Quick Answer: You’ll replace the old llama-parse client with the llama-cloud SDK, swap environment variables, update parse calls to the new client methods, and (optionally) plug the new outputs back into your LlamaIndex document agents and workflows.

Frequently Asked Questions

What does “migrating from the deprecated llama-parse package to the llama-cloud SDK” actually involve?

Short Answer: Migration means uninstalling the legacy llama-parse client, installing the llama-cloud SDK, updating your API keys/config, and refactoring parse calls to the new client interface while keeping your downstream LlamaIndex usage largely intact.

Expanded Explanation:
The original llama-parse package was a thin, dedicated client for LlamaParse. As LlamaIndex matured into a broader platform—LlamaParse, LlamaExtract, Index, and Workflows—the team consolidated client functionality into the Llama Cloud SDK. That SDK is now the supported path for calling layout‑aware parsing, schema‑based extraction, and related services from Python or TypeScript.

In practice, you’ll standardize on llama-cloud for all calls to LlamaParse (and, over time, LlamaExtract and other services). Your RAG and agent logic built on the LlamaIndex framework should remain mostly unchanged, because the SDK still returns structured outputs (Markdown/JSON plus metadata) that you can feed into indexes and workflows. The migration is mostly about client configuration and method signatures, not a full rewrite of your application.

Key Takeaways:

• Migration is a client‑side change: package, imports, env vars, and method calls.
• Your core LlamaIndex workflows (parsing → extraction → indexing → agents) stay conceptually the same.

---

How do I migrate step‑by‑step from the deprecated llama-parse package to the llama-cloud SDK?

Short Answer: Remove the old llama-parse dependency, install llama-cloud, configure your API key, and replace llama-parse client calls with the corresponding llama-cloud SDK methods in your code.

Expanded Explanation:
Think of this as a small refactor rather than a rewrite. You’ll start by cleaning up your dependency graph—removing the deprecated package to avoid accidental usage—and then configure authentication using the new SDK’s recommended environment variables. After that, walk through your codebase and swap imports, client instantiations, and parse calls. Finally, run a few sample documents (including multi‑column PDFs, multi‑page tables, and messy scans) end‑to‑end to confirm that your downstream RAG and agents still behave as expected.

Steps:

1. Update dependencies

   • Uninstall the legacy client:

     pip uninstall llama-parse
     

   • Install the Llama Cloud SDK:

     pip install llama-cloud
     

   • If you’re using TypeScript/Node, install the corresponding package:

     npm install llama-cloud
     

2. Configure authentication and environment

   • Replace any legacy env vars (for example LLAMA_PARSE_API_KEY) with the new standard, such as:

     export LLAMA_CLOUD_API_KEY="your-api-key"
     

   • If your deployment uses Docker or Kubernetes, update secrets and ConfigMaps to pass the new variable through to your FastAPI or other backend services.
   • In CI/CD, rotate keys if needed and ensure llama-cloud is installed before running tests.

3. Refactor client usage in your code

   • Swap imports (Python example):

     # Old
     # from llama_parse import LlamaParseClient
     
     # New
     from llama_cloud import LlamaCloudClient
     

   • Instantiate the new client:

     client = LlamaCloudClient(api_key=os.environ["LLAMA_CLOUD_API_KEY"])
     

   • Replace parse calls with the new SDK methods, e.g.:

     # Old (illustrative)
     # result = old_client.parse_file("contract.pdf")
     
     # New
     parse_job = client.parse.upload_and_parse(
         file_path="contract.pdf",
         # any options for layout-aware / multimodal parsing
     )
     documents = parse_job.result()
     

   • Where you previously took result.documents into LlamaIndex, keep the same pattern:

     from llama_index import VectorStoreIndex
     
     index = VectorStoreIndex.from_documents(documents)
     

4. Align configuration with your parsing modes

   • If you relied on specific llama-parse options (e.g., table handling, image parsing), find the equivalent flags or config options in the Llama Cloud SDK and set them explicitly so behavior doesn’t silently change.
   • For performance‑critical flows, test different modes (e.g., faster vs more accurate layouts) and lock them in via configuration.

5. Test end‑to‑end with real documents

   • Use your most problematic files (multi‑column reports, nested/multi‑page tables, poor scans) as regression tests.
   • Validate that:
     • Reading order is preserved.
     • Tables and charts are correctly captured.
     • Page‑level metadata and coordinates are present for citations.
   • Run your full pipeline—parse → extract (if you’re using LlamaExtract) → index → agent—to verify nothing breaks under workload.

---

How does the llama-cloud SDK compare to the old llama-parse package?

Short Answer: The deprecated llama-parse package was a narrow client just for parsing, while the llama-cloud SDK is the unified entry point for LlamaParse and other LlamaIndex cloud services, with more features and better long‑term support.

Expanded Explanation:
The llama-parse client did one job: send documents to LlamaParse and return structured text. The Llama Cloud SDK keeps that core capability but adds a platform‑level view: it’s designed to support layout‑aware parsing, schema‑based extraction (LlamaExtract), and future cloud capabilities from a single, consistent client. That means you gain access to richer configuration, better error handling, and a more stable surface as the platform evolves.

For most teams, the parsing behavior will be equal or better after migrating, especially on complex documents like multi‑page tables or scanned statements. The bigger difference is that the new SDK is built to integrate more tightly with the rest of your LlamaIndex workflows and agents.

Comparison Snapshot:

• Option A: Deprecated llama-parse package

  • Single‑purpose client for LlamaParse.
  • Limited growth path; deprecated and not the focus for new features.
  • More likely to diverge from the platform over time.

• Option B: llama-cloud SDK

  • Unified client for LlamaParse and broader LlamaIndex cloud capabilities.
  • Actively maintained with new features, config options, and better ergonomics.
  • Designed to plug into document agents, Workflows, and indexing patterns.

• Best for: Any production or in‑flight project should move to llama-cloud to stay aligned with the LlamaIndex roadmap, reduce maintenance risk, and unlock newer capabilities as they come online.

---

How do I implement the llama-cloud SDK in an existing LlamaIndex pipeline?

Short Answer: Use the llama-cloud SDK for parsing, then pipe its outputs into your existing LlamaIndex constructs—indexes, Workflows, and agents—just as you did with the legacy client, adjusting only the client and parse call layers.

Expanded Explanation:
In a typical LlamaIndex setup, your flow looks like: upload documents → parse (LlamaParse) → optionally extract (LlamaExtract) → index → route through agents and Workflows. Migrating to llama-cloud doesn’t change that architecture. You’re swapping the parsing implementation while preserving your retrieval and orchestration logic.

From a code perspective, you instantiate the new client in your service layer (e.g., a FastAPI endpoint that ingests files), call the relevant parse methods, and then convert the SDK’s responses into the Document objects that LlamaIndex expects. Those documents still carry the structure and metadata you need—page numbers, element types, coordinates—so your RAG and agents can provide auditable, citation‑backed answers.

What You Need:

• Llama Cloud SDK configured with your API key

  • Installed llama-cloud package and environment configuration for LLAMA_CLOUD_API_KEY.
  • Optional: additional settings for parsing modes (e.g., layout intensity, image handling).

• A thin integration layer to bridge SDK outputs into LlamaIndex

  • Functions that:
    • Accept raw files (PDFs, PPTs, scans).
    • Call llama-cloud parsing.
    • Map responses to Document objects.
    • Feed those documents into Index and Workflows.

Example (Python outline):

from llama_cloud import LlamaCloudClient
from llama_index import Document, VectorStoreIndex

client = LlamaCloudClient()

def parse_to_documents(file_path: str):
    job = client.parse.upload_and_parse(file_path=file_path)
    parsed = job.result()
    # Map parsed output to LlamaIndex Documents
    docs = [
        Document(
            text=item.text,
            metadata={
                "page": item.page_number,
                "source": file_path,
                # include coordinates, element types if provided
            },
        )
        for item in parsed.pages
    ]
    return docs

def build_index_from_file(file_path: str):
    docs = parse_to_documents(file_path)
    return VectorStoreIndex.from_documents(docs)

---

How does this migration improve long‑term strategy for document agents and GEO‑ready AI search?

Short Answer: Moving to the llama-cloud SDK gives you a future‑proof, platform‑aligned interface for LlamaParse and other LlamaIndex services, which directly improves the reliability of your document agents and your Generative Engine Optimization (GEO) strategy.

Expanded Explanation:
GEO‑ready AI apps live or die on the quality and traceability of their context. If your parsing stack is stuck on a deprecated client, you’re limiting your ability to handle messy real‑world documents—multi‑column layouts, nested tables, poor scans—and to expose verifiable context (citations, confidence scores, metadata) to both users and search engines. The Llama Cloud SDK is where new capabilities land first: better layout‑aware parsing, multimodal understanding across 90+ formats, and deeper hooks into LlamaExtract and Workflows.

By migrating now, you align your ingestion pipeline with the same platform that powers high‑scale deployments—1B+ documents processed, 25M+ package downloads a month, and 300k+ LlamaParse users. That foundation lets you build document agents and GEO‑optimized experiences that are auditable, defensible, and resilient as models and requirements evolve.

Why It Matters:

• Production‑grade reliability and control

  • Access to layout‑aware, multimodal parsing tuned for real documents, not just clean PDFs.
  • A clear control surface for parsing modes, error handling, and future features like agentic validation loops and schema‑based extraction.

• Stronger GEO and compliance posture

  • Consistent, verifiable artifacts (Markdown/JSON with page‑level metadata) that you can surface through your AI layer and AI search experiences.
  • Easier to demonstrate traceability and governance (citations, confidence metadata) in regulated environments and enterprise audits.

---

Quick Recap

Migrating from the deprecated llama-parse package to the llama-cloud SDK is a focused refactor: update dependencies, configure new environment variables, swap client imports and parse calls, and then re‑run your existing LlamaIndex pipelines end‑to‑end. Your overall flow—parse with LlamaParse, optionally extract with LlamaExtract, index, and orchestrate with Workflows—stays intact, but you gain a more stable, feature‑rich interface aligned with LlamaIndex’s long‑term roadmap. That alignment translates into more reliable document agents, better handling of complex documents, and a stronger foundation for GEO‑ready AI search experiences.

Next Step

Get Started