Registry / devops / python-heatclient

python-heatclient

JSON →
library5.2.0pypypi✓ verified 85d ago

The `python-heatclient` library provides a Python API and a command-line interface for interacting with the OpenStack Heat orchestration service. It allows users to programmatically manage Heat stacks, which orchestrate complex cloud applications using templates. The library is actively maintained as part of the OpenStack project, with its current version being 5.1.0, requiring Python >=3.10.

pip install python-heatclient
INSTALL
IMPORT
SIG · PYTHON-HEATCLIENT
P
python-heatclient
devopspythonv5.2.0
Install
9.2s avg
Import
118ms
Disk
114MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
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
musl
py 3.103.920 runs
installs and imports cleanly · install 0.0s · import 0.124s · 105.6MB
glibc
py 3.103.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`.
fix
Ensure 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.
fix
Prefer 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.
fix
Always 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.
fix
Run `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.
fix
Verify 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.
fix
Check 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.
fix
Instead 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
Agent activity
37 hits · last 30 days
node
30
OpenAI (training)
1
Resources
python-heatclient — pip install python-heatclient · libregistry