Install & Compatibility
Where this runs
tested against v0.2.12 · 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.920 runs
installs and imports cleanly · install 0.0s · import 0.884s · 209.3MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 12.2s · import 0.916s · 202MB
210MB installed
● package 210MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
LlamaStackClient
✓ from llama_stack_client import LlamaStackClient
This quickstart demonstrates how to initialize the LlamaStackClient and perform a basic model listing and inference request. It assumes a Llama Stack server is already running and accessible, for instance, locally via Docker.
import os
from llama_stack_client import LlamaStackClient
# Ensure a Llama Stack server is running, e.g., locally at http://localhost:8321.
# Authentication typically uses the LLAMA_STACK_CLIENT_API_KEY environment variable.
# Example: export LLAMA_STACK_CLIENT_API_KEY="your_api_key"
# You can also set the base URL via LLAMA_STACK_BASE_URL environment variable.
client = LlamaStackClient(
base_url=os.environ.get("LLAMA_STACK_BASE_URL", "http://localhost:8321"),
api_key=os.environ.get("LLAMA_STACK_CLIENT_API_KEY", "dummy_key_for_testing_if_not_set"),
)
try:
# List available models
models = client.models.list()
print("Available models:", [model.id for model in models.data])
# Perform simple inference using the Responses API
if models.data:
response = client.responses.create(
model=models.data[0].id, # Use the first available model
input="Write a haiku about coding.",
)
print("\nHaiku from Llama Stack:", response.output_text)
else:
print("\nNo models found on the Llama Stack server.")
except Exception as e:
print(f"An error occurred: {e}")
print("Please ensure your Llama Stack server is running and accessible (e.g., via Docker), and the API key is set correctly.")
Debug
Known issues
breakingThe `agents` API was renamed to `responses` API in `v0.7.0-alpha.1`. Code using `client.agents` will no longer work.fixUpdate all calls from `client.agents.*` to `client.responses.*`.
affects: >=0.7.0-alpha.1
breakingBreaking changes were introduced to the `GET /chat/completions/{completion_id}` and `/files/{file_id}` endpoints in `v0.7.0-alpha.1` to eliminate conformance issues.fixReview and update code interacting with `client.chat.completions.retrieve()` and `client.files.retrieve()` methods.
affects: >=0.7.0-alpha.1
breakingConsistency improvements were made to post-training API endpoints in `v0.6.1-alpha.1`, which may involve API surface changes.fixReview documentation and update code using post-training APIs accordingly.
affects: >=0.6.1-alpha.1
gotchaThe `llama-stack-client` library is currently in alpha (`--pre`) release status. This implies that breaking changes and API instability are frequent and expected across minor versions. It is recommended to pin exact versions.fixPin your `llama-stack-client` version in `requirements.txt` or `pyproject.toml` (e.g., `llama-stack-client==0.7.2`) to avoid unexpected breakage.
affects: All alpha versions
gotchaThis library is a client for the Llama Stack API. It requires a separate Llama Stack server instance to be running and accessible. This client library does not include the server itself.fixEnsure a Llama Stack server is deployed and running (e.g., via Docker) before attempting to use this client.
affects: All versions
gotchaFor authentication, the client primarily relies on the `LLAMA_STACK_CLIENT_API_KEY` environment variable. If this is not set, API calls may fail or use a dummy key.fixSet the `LLAMA_STACK_CLIENT_API_KEY` environment variable with your actual API key before initializing the client, or pass it explicitly during client instantiation.
affects: All versions
gotchaThe Responses API, a central feature for server-side agentic orchestration, is still under active development. While usable, some parts of its OpenAI-compatible implementation may still be unimplemented.fixRefer to the official Llama Stack documentation for the most up-to-date information on the Responses API capabilities and known limitations.
affects: All alpha versions
Upgrade
Version history
0.7.4latest on PyPI · released May 28, 2026
Audit
Dependencies
httpxrequiredUsed as the underlying HTTP client for both synchronous and asynchronous operations.