Registry / llm-agents / llama-cloud

llama-cloud

JSON →
library2.15.0pypypi✓ verified 24d ago

The `llama-cloud` Python SDK is the official library for interacting with the Llama Cloud API, providing convenient access to services like LlamaParse for agentic OCR and document processing, structured data extraction, document classification, and RAG ingestion. The library offers both synchronous and asynchronous clients and is actively maintained with frequent releases, currently at version 2.3.0.

pip install llama-cloud
INSTALL
IMPORT
SIG · LLAMA-CLOUD
L
llama-cloud
llm-agentspythonv2.15.0
Install
4.3s avg
Import
1648ms
Disk
36MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v2.15.0 · 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
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 1.738s · 37.4MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 4.3s · import 1.558s · 37MB
36MB installed
● package 36MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

LlamaCloud
from llama_cloud import LlamaCloud
AsyncLlamaCloud
from llama_cloud import AsyncLlamaCloud
APIError
from llama_cloud import APIError
import llama_cloud; try: ... except llama_cloud.APIError as e:
While `import llama_cloud` works, importing `APIError` directly is cleaner for exception handling.

Initializes the Llama Cloud client using an API key from environment variables and demonstrates how to create a document parsing job. For actual usage, replace `dummy_file_id` with an ID obtained from uploading a file via `client.files.create()`.

import os from llama_cloud import LlamaCloud from pathlib import Path # Ensure LLAMA_CLOUD_API_KEY is set in your environment variables # e.g., os.environ['LLAMA_CLOUD_API_KEY'] = 'llx-...' or using a .env file client = LlamaCloud( api_key=os.environ.get('LLAMA_CLOUD_API_KEY', '') ) # Example: Upload a dummy file and create a parsing job # Replace with a real file path for actual usage # file_path = Path("path/to/your/document.pdf") # with open(file_path, "rb") as f: # file_obj = client.files.create( # file=(file_path.name, f.read(), "application/pdf"), # purpose="parse", # ) # For demonstration, simulate a file_id to create a parsing job # In a real scenario, file_id would come from client.files.create() or an existing file. dummy_file_id = "your-example-file-id" # Replace with actual file_id if uploading if not dummy_file_id: print("Please provide a valid file_id or upload a file first.") else: try: job = client.parsing.create( tier="agentic", # or "fast", "cost_effective" version="latest", file_id=dummy_file_id, # For example, to get markdown output: output_options={ "markdown": { "tables": { "output_tables_as_markdown": True } } }, expand=["markdown"] ) print(f"Created parsing job with ID: {job.id}") # You would typically poll the job status and retrieve results here # For example, using client.parsing.get_job_result(job.id) except Exception as e: print(f"An error occurred: {e}")
Debug
Known issues
breakingThe v2.0.0 release introduced significant breaking changes, including the removal of the v1 extraction resource and a restructure of metadata. If you were using `extraction` features prior to v2.0.0, your code will need updates.
fix
Review the official Llama Cloud API documentation for updated `extraction` and `parse` endpoint usage and new metadata structures. Specifically, refer to the 'Migration Guide: Parse Upload Endpoint v1 to v2' for detailed changes.
affects: >=2.0.0
breakingThe `llama-cloud-services` package is deprecated and will no longer be maintained after May 1, 2026. This older SDK has different import paths and API surface areas.
fix
Migrate your codebase to use the `llama-cloud` package (version >=1.0) and update all imports and API calls accordingly. The new SDK provides improved performance and active development.
affects: <1.0.0 (of `llama-cloud-services`)
gotchaHardcoding API keys directly in your application code is a security risk. API keys are user and project-scoped.
fix
Always store your `LLAMA_CLOUD_API_KEY` in environment variables or a secure key management service. The SDK automatically picks up `LLAMA_CLOUD_API_KEY` from environment variables, or it can be passed via the `api_key` parameter during client initialization using `os.environ.get('LLAMA_CLOUD_API_KEY')`.
affects: All
gotchaLlamaParse API v2 introduced structured configuration objects (`input_options`, `output_options`, `processing_options`) instead of a flat list of parameters from v1. Old parameter names or structures from v1 will not work with v2 endpoints.
fix
Consult the LlamaParse API v2 documentation for the correct use of `tier` and the new configuration objects when calling `client.parsing.create()` or `client.parsing.parse()`.
affects: >=2.0.0
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'llama_cloud'
The `llama-cloud` Python package is not installed in your active Python environment.
fix
Run `pip install llama_cloud` to install the library.
llama_cloud.APIError: 401 Unauthorized: Invalid API Key
Your Llama Cloud API key is missing, incorrect, expired, or does not have the necessary permissions.
fix
Ensure the `LLAMA_CLOUD_API_KEY` environment variable is set with a valid key, or pass `api_key='your_api_key_here'` directly to the `LlamaCloud` client constructor.
ImportError: cannot import name 'LlamaParse' from 'llama_cloud_services.parse'
You are attempting to import from the deprecated `llama_cloud_services` or `llama_parse` packages. The functionality has been integrated directly into the `llama-cloud` package.
fix
Migrate your code to use the `llama_cloud` package directly. For parsing, initialize the `LlamaCloud` client and use `client.parsing.create()`.
llama_cloud.APIError: 400 Bad Request: Either file, input_url, or input_s3_path must be provided.
When creating a parsing job, you did not provide any of the required input sources: a local file, a URL, or an S3 path.
fix
Ensure you provide exactly one of the `file`, `input_url`, or `input_s3_path` parameters when calling `client.parsing.create()`.
ValidationError: 1 validation error for ParsingModel[List[llama_cloud.types.pipeline.Pipeline]] __root__ -> 0 -> preset_retrieval_parameters -> retrieval_mode value is not a valid enumeration member
There is a mismatch between the `retrieval_mode` value returned by the Llama Cloud API and what your local client SDK (Pydantic model) expects, often due to an outdated `llama-cloud` package or using a deprecated `retrieval_mode` value.
fix
Update your `llama-cloud` package to the latest version using `pip install --upgrade llama_cloud`. If the error persists, check the official documentation for supported `retrieval_mode` values.
Upgrade
Version history
2.15.0latest on PyPI · released Aug 28, 2026
Audit
Dependencies

No dependency data recorded yet.

Agent activity
10 hits · last 30 days
node
8
OpenAI (training)
1
Resources
llama-cloud — pip install llama-cloud · libregistry