Install & Compatibility
Where this runs
tested against v5.2.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.920 runs
installs and imports cleanly · install 0.0s · import 0.124s · 105.6MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 9.2s · import 0.111s · 107MB
114MB installed
● package 114MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Client
✓ from heatclient import client as heat_client
✗ import heatclient.client
Common practice to alias the client module for clarity, as 'client' is a generic name.
Session
✓ from keystoneauth1.session import Session
✗ from keystoneclient.v3 import Client as Keystone_Client
For authentication, `keystoneauth1.session.Session` is the recommended approach for creating an authenticated session, not direct `keystoneclient` imports which are for the identity API itself.
get_plugin_loader
✓ from keystoneauth1.loading import get_plugin_loader
Used to dynamically load authentication plugins (e.g., 'password', 'v3password') without hardcoding classes.
This quickstart demonstrates how to authenticate with OpenStack Keystone and then initialize the Heat client to list existing Heat stacks. It uses the `keystoneauth1` library for robust authentication, which is essential for interacting with OpenStack services. Replace placeholder credentials with your actual OpenStack environment details.
import os
from keystoneauth1 import loading
from keystoneauth1.session import Session
from heatclient import client as heat_client
# --- Authentication --- (replace with your OpenStack credentials or environment variables)
# For production, consider using environment variables (OS_AUTH_URL, OS_USERNAME, etc.)
# and 'keystoneauth1.loading.load_auth_from_options' or 'load_from_env'.
# For simplicity, using hardcoded values for quickstart, but highly discouraged in production.
AUTH_URL = os.environ.get('OS_AUTH_URL', 'http://your-openstack-ip/identity/v3')
USERNAME = os.environ.get('OS_USERNAME', 'admin')
PASSWORD = os.environ.get('OS_PASSWORD', 'your-password')
PROJECT_NAME = os.environ.get('OS_PROJECT_NAME', 'admin')
USER_DOMAIN_NAME = os.environ.get('OS_USER_DOMAIN_NAME', 'Default')
PROJECT_DOMAIN_NAME = os.environ.get('OS_PROJECT_DOMAIN_NAME', 'Default')
# Load the password authentication plugin
loader = loading.get_plugin_loader('password')
auth = loader.load_from_options(
auth_url=AUTH_URL,
username=USERNAME,
password=PASSWORD,
project_name=PROJECT_NAME,
user_domain_name=USER_DOMAIN_NAME,
project_domain_name=PROJECT_DOMAIN_NAME
)
# Create a Keystone session
sess = Session(auth=auth)
# Create a Heat client
# API version '1' is commonly used. 'public' endpoint type is standard.
heat_client_instance = heat_client.Client(
'1',
session=sess,
endpoint_type='public',
service_type='orchestration'
)
# --- Example Usage: List Stacks ---
try:
print('Listing Heat stacks:')
for stack in heat_client_instance.stacks.list():
print(f" - Name: {stack.stack_name}, Status: {stack.stack_status}, ID: {stack.id}")
except Exception as e:
print(f"Error listing stacks: {e}")
heat --version
Debug
Known issues
breakingPython 2.7 support has been officially dropped. `python-heatclient` versions starting from Xena series (e.g., 2.x and later) and specifically the current 5.1.0 version, require Python 3.6 or newer, with the PyPI metadata explicitly stating `>=3.10`.fixEnsure your environment uses Python 3.10 or a compatible newer version. Upgrade your Python interpreter if necessary.
affects: <=1.x (Python 2.7), >=2.x (Python 3.6+), Current 5.1.0 (Python 3.10+)
gotchaOpenStack CLI commands are progressively consolidating into the unified `python-openstackclient`. While direct `heat` commands still exist, many functionalities are moving to `openstack stack ...` subcommands. Users familiar with older `heat` CLI tools should be aware of this shift.fixPrefer using `openstack stack` commands when available for new development or scripting, and consult `openstack help stack` for the most up-to-date syntax. `python-heatclient` continues to provide the programmatic API.
affects: All versions when integrating with `python-openstackclient` (especially newer OpenStack releases)
gotchaAuthentication for the `heatclient` Python API requires constructing an authenticated session using `keystoneauth1`. Directly passing authentication tokens or credentials to `heatclient.Client` might be deprecated or incorrect in newer versions. Relying solely on shell environment variables (like `OS_USERNAME`) without explicitly loading them via `keystoneauth1` will not work for the programmatic client.fixAlways use `keystoneauth1.loading` and `keystoneauth1.session.Session` to create an authenticated session and pass this session object to `heatclient.Client`.
affects: All versions, increasingly critical in newer OpenStack deployments
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'heatclient'
The `python-heatclient` library is not installed in the current Python environment.
fixRun `pip install python-heatclient` to install the library.
heatclient.common.exception.Unauthorized: The request you have made requires authentication. (HTTP 401)
The authentication credentials (username, password, project, domain, auth URL) provided to `keystoneauth1` are incorrect, expired, or missing.
fixVerify your OpenStack credentials and `OS_AUTH_URL`. Ensure all required authentication parameters are correctly configured and passed to `keystoneauth1.loading.get_plugin_loader().load_from_options()`.
heatclient.common.exception.ClientException: Could not find resource for service type orchestration.
The Heat service endpoint could not be discovered or is unavailable/misconfigured in the OpenStack service catalog.
fixCheck the `OS_AUTH_URL` and ensure the Heat service (orchestration) is registered and accessible in your OpenStack deployment. Verify network connectivity to the Keystone and Heat API endpoints.
TypeError: Client() got an unexpected keyword argument 'auth_token'
You are attempting to pass an authentication token directly to `heatclient.Client`, which expects a `keystoneauth1.session.Session` object.
fixInstead of passing `auth_token`, create a `keystoneauth1.session.Session` object with your authentication details and pass it using the `session` keyword argument: `heat_client.Client('1', session=my_session)`. Upgrade
Version history
5.2.0latest on PyPI · released May 18, 2026
Audit
Dependencies
python-cliffrequiredCommand line interface framework
python-iso8601requiredISO 8601 date parsing
python-keystoneauth1requiredOpenStack Identity authentication library
python-openstackclientrequiredIntegration with the unified OpenStack CLI
python-osc-librequiredOpenStack client library utilities
python-oslo-i18nrequiredInternationalization support for OpenStack projects
python-oslo-serializationrequiredSerialization utilities for OpenStack projects
python-oslo-utilsrequiredCommon utilities for OpenStack projects
python-pbrrequiredSetuptools enhancements for OpenStack projects
python-prettytablerequiredFormatted table output
python-requestsrequiredHTTP library for making API calls
python-swiftclientrequiredOpenStack Object Storage (Swift) client (optional, for specific Heat features)
python-yamlrequiredYAML parsing for templates