Install & Compatibility
Where this runs
tested against v9.9.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.030s · 52.1MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 4.9s · import 0.996s · 53MB
53MB installed
● package 53MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
client
✓ from cinderclient.v3 import client
✗ from cinderclient.v1 import client
Cinder API v3 is the current recommended version. Cinder API v1 and v2 are deprecated.
This quickstart demonstrates how to authenticate with OpenStack Keystone using `keystoneauth1` and then create a Cinder client to list volumes. It is recommended to set OpenStack credentials as environment variables (`OS_AUTH_URL`, `OS_USERNAME`, `OS_PASSWORD`, `OS_PROJECT_ID`/`OS_PROJECT_NAME`, `OS_REGION_NAME`, `OS_VOLUME_API_VERSION`) for security and ease of use. The client is initialized for Cinder API v3, which is the recommended version.
import os
from keystoneauth1 import loading
from keystoneauth1 import session
from cinderclient.v3 import client as cinder_client
# Set environment variables or replace with actual values
OS_AUTH_URL = os.environ.get('OS_AUTH_URL', 'http://localhost:5000/v3')
OS_USERNAME = os.environ.get('OS_USERNAME', 'admin')
OS_PASSWORD = os.environ.get('OS_PASSWORD', 'password')
OS_PROJECT_ID = os.environ.get('OS_PROJECT_ID', 'project_id') # Or OS_PROJECT_NAME
OS_REGION_NAME = os.environ.get('OS_REGION_NAME', 'RegionOne')
OS_VOLUME_API_VERSION = os.environ.get('OS_VOLUME_API_VERSION', '3')
# Load the authentication plugin
loader = loading.get_plugin_loader('password')
auth = loader.load_from_options(
auth_url=OS_AUTH_URL,
username=OS_USERNAME,
password=OS_PASSWORD,
project_id=OS_PROJECT_ID, # Use project_id or project_name
user_domain_name='Default', # Often 'Default' for typical OpenStack setups
project_domain_name='Default'
)
# Create a session
sess = session.Session(auth=auth)
# Create the Cinder client
cinder = cinder_client.Client(OS_VOLUME_API_VERSION, session=sess, region_name=OS_REGION_NAME)
# Example: List volumes
try:
volumes = cinder.volumes.list()
print(f"Successfully listed volumes: {volumes}")
except Exception as e:
print(f"Error listing volumes: {e}")
cinder --version
Debug
Known issues
deprecatedCinder API v2 is officially deprecated. While `python-cinderclient` might still support it for backward compatibility, new development and existing deployments should migrate to Cinder API v3.fixAlways import `client` from `cinderclient.v3` (e.g., `from cinderclient.v3 import client`) and set `OS_VOLUME_API_VERSION=3` in your environment or client initialization.
affects: < 9.x (specifically older API versions accessed through the client)
gotchaAuthentication relies heavily on environment variables (e.g., `OS_USERNAME`, `OS_PASSWORD`, `OS_AUTH_URL`, `OS_PROJECT_ID`/`OS_TENANT_NAME`, `OS_REGION_NAME`). Incorrectly setting these, or not providing them when expected, will lead to authentication failures.fixEnsure all necessary `OS_` environment variables are correctly set or explicitly passed during client initialization. Using `keystoneauth1.loading.get_plugin_loader('password').load_from_options` helps manage these. affects: All versions
deprecatedThe `--endpoint-type` CLI option has been deprecated. Users should utilize `--os-endpoint-type` instead when interacting via the command line.fixWhen using the `cinder` CLI, replace `--endpoint-type` with `--os-endpoint-type`.
affects: All versions
breakingHistorically, there was a breaking change in versions 1.2.0 and 1.2.2 related to 'version discovery breaks deployments using proxies,' which was reverted in v1.3.0. This highlights potential issues with automatic version discovery and the importance of explicitly specifying API versions.fixAlways explicitly specify the Cinder API version (e.g., '3') during client initialization to avoid unexpected behavior, especially in complex network environments with proxies.
affects: 1.2.0, 1.2.2
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'cinderclient'
The python-cinderclient library is not installed in your current Python environment.
fixpip install python-cinderclient
ERROR (Unauthorized): The request you have made requires authentication. (HTTP 401)
OpenStack authentication credentials (e.g., environment variables or clouds.yaml) are missing, incorrect, or expired, preventing access to the Cinder service.
fixEnsure OpenStack environment variables (like OS_AUTH_URL, OS_USERNAME, OS_PASSWORD, OS_PROJECT_NAME, OS_REGION_NAME) are correctly set and sourced, or that ~/.config/openstack/clouds.yaml is properly configured.
ERROR (NotFound): No Cinder endpoint found.
The configured OpenStack region or authentication scope does not contain a registered Cinder (Block Storage) service endpoint, or the service catalog is unavailable.
fixVerify that your OS_REGION_NAME and OS_AUTH_URL environment variables are correct for your OpenStack environment and that the Cinder service is enabled and accessible in the specified region.
AttributeError: 'Client' object has no attribute 'create_volume'
Volume creation methods are not directly on the top-level Client object but are accessed via the 'volumes' manager attribute.
fixAccess volume-related operations through the 'volumes' manager: `cinder_client.volumes.create(...)`
Upgrade
Version history
9.9.0latest on PyPI · released Mar 2, 2026
Audit
Dependencies
keystoneauth1requiredRequired for authentication with OpenStack Keystone.
oslo.utilsrequiredCommon OpenStack utility library.
requestsrequiredHTTP library for making API calls.