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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 1.738s · 37.4MB
glibcpy 3.10–3.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.fixReview 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.fixMigrate 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.fixAlways 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.fixConsult 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.
fixRun `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.
fixEnsure 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.
fixMigrate 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.
fixEnsure 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.
fixUpdate 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.