Install & Compatibility
Where this runs
tested against v4.13.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.288s · 66.4MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 5.9s · import 1.164s · 68MB
71MB installed
● package 71MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
openstack
✓ import openstack
This is the primary and recommended import for accessing the SDK's functionality, including connection management and service proxies.
Connection
✓ from openstack import connection
✗ from openstack.connection import Connection
While technically possible, direct import of `Connection` is less common. The `openstack.connect()` factory function is the idiomatic way to create a connection instance, returning a `Connection` object.
Server
✓ conn.compute.servers()
✗ from openstack.compute.v2 import server; server.Server.list(session=conn.compute)
Directly using `Resource` classes from submodules like `openstack.compute.v2.server` is a lower-level pattern. The recommended approach is to use the service proxies available through the `Connection` object (e.g., `conn.compute.servers()`) for higher-level operations.
This quickstart demonstrates how to establish a connection to an OpenStack cloud, list images and flavors, and then optionally create and delete a compute instance (server). It uses environment variables for authentication and resource naming for simplicity. For production, `clouds.yaml` is recommended. Ensure `OS_AUTH_URL`, `OS_USERNAME`, `OS_PASSWORD`, `OS_PROJECT_NAME`, and optionally `OS_CLOUD` are set in your environment, along with `OS_TEST_IMAGE`, `OS_TEST_FLAVOR`, `OS_TEST_NETWORK`, and `OS_TEST_KEYPAIR` for server creation.
import os
import openstack
import time
# Configure connection via environment variables for a quickstart
# In a real application, consider using a clouds.yaml file for more robust configuration.
# Example: export OS_CLOUD='devstack' or set individual OS_ prefixed variables.
# You can also pass auth parameters directly to openstack.connect()
# Initialize and turn on debug logging (optional, but useful for troubleshooting)
openstack.enable_logging(debug=True)
try:
# Establish a connection to your OpenStack cloud
# 'envvars' tells openstacksdk to look for OS_CLOUD or individual OS_ prefixed environment variables
conn = openstack.connect(cloud='envvars')
print("Successfully connected to OpenStack!")
# List available images
print("\nAvailable images:")
for image in conn.image.images():
print(f" ID: {image.id}, Name: {image.name}")
# List available flavors (instance types)
print("\nAvailable flavors:")
for flavor in conn.compute.flavors():
print(f" ID: {flavor.id}, Name: {flavor.name}, RAM: {flavor.ram}MB, VCPUs: {flavor.vcpus}")
# --- Example: Create a new server (instance) ---
# Requires an existing image, flavor, network, and keypair in your OpenStack cloud.
# Replace with actual values from your environment or obtained from the above listings.
IMAGE_NAME = os.environ.get('OS_TEST_IMAGE', 'cirros')
FLAVOR_NAME = os.environ.get('OS_TEST_FLAVOR', 'm1.tiny')
NETWORK_NAME = os.environ.get('OS_TEST_NETWORK', 'private') # Or 'public' if applicable
KEYPAIR_NAME = os.environ.get('OS_TEST_KEYPAIR', 'my_keypair')
SERVER_NAME = f"test-sdk-server-{int(time.time())}"
# Find the image, flavor, and network by name
image = conn.image.find_image(IMAGE_NAME)
flavor = conn.compute.find_flavor(FLAVOR_NAME)
network = conn.network.find_network(NETWORK_NAME)
keypair = conn.compute.find_keypair(KEYPAIR_NAME)
if not all([image, flavor, network, keypair]):
print("\nError: One or more required resources (image, flavor, network, keypair) not found. Skipping server creation.")
else:
print(f"\nCreating server '{SERVER_NAME}'...")
server = conn.compute.create_server(
name=SERVER_NAME,
image_id=image.id,
flavor_id=flavor.id,
networks=[{"uuid": network.id}],
key_name=keypair.name
)
print(f"Server '{SERVER_NAME}' created (ID: {server.id}). Waiting for active status...")
conn.compute.wait_for_server(server)
print(f"Server '{SERVER_NAME}' is now {server.status}.")
print(f"Access IPv4: {getattr(server, 'access_ipv4', 'N/A')}")
# Cleanup: Delete the created server
print(f"\nDeleting server '{SERVER_NAME}' (ID: {server.id})...")
conn.compute.delete_server(server.id)
conn.compute.wait_for_delete(server)
print(f"Server '{SERVER_NAME}' deleted.")
except openstack.exceptions.SDKException as e:
print(f"An OpenStack SDK error occurred: {e}")
except Exception as e:
print(f"An unexpected error occurred: {e}")
Debug
Known issues
breakingMajor breaking changes were introduced in `openstacksdk` versions `0.99.0` and `1.0.0`. The `Connection` interface now consistently utilizes `Resource` interfaces under the hood, and many API responses, which previously returned `Munch` objects, now return standard Python dictionaries. Additionally, many keys in the returned data were renamed.fixUpdate your code to expect dictionary-like access for resource properties and adjust to new key names. Refer to the official release notes for `0.99.0` and `1.0.0` for detailed changes. For example, use `.to_dict()` if you explicitly need a dictionary representation from a resource object.
affects: >=0.99.0, >=1.0.0
gotchaOpenStack services often use 'microversions' for their APIs. If not explicitly specified, `openstacksdk` will default to the lowest API version supported by the service. This can lead to missing features or unexpected behavior if you expect a newer API version's functionality.fixFor services supporting microversions, explicitly specify the desired API version via connection parameters (e.g., `compute_api_version='2.latest'`) or service proxy arguments. Consult the OpenStack API reference for service-specific microversion details.
affects: All versions
gotchaSome resource attributes in `openstacksdk` are lazy-loaded, meaning they are not populated immediately when a resource object is created or returned from a list operation. For example, `block_device_mapping` or `networks` for a `Server` object might only be present after a `server.fetch()` call.fixIf you require specific attributes that might be lazy-loaded, ensure you call the `fetch()` method on the resource object to retrieve its full details from the OpenStack API before accessing those attributes.
affects: All versions
gotchaAuthentication and configuration can be a common source of errors. Incorrect `clouds.yaml` file formats, missing environment variables, or mixing OpenStack Identity API versions (v2 vs. v3) in configuration can lead to authentication failures.fixCarefully review your `clouds.yaml` file (if used) and environment variables for correctness. Ensure `auth_url` points to the correct Identity API version endpoint (e.g., `/v3`). The SDK will try to detect the API version, but explicit configuration helps. `openstack.enable_logging(debug=True)` can provide verbose authentication debug information.
affects: All versions
deprecated`openstacksdk` utilizes a warnings infrastructure (e.g., `openstack.warnings.OpenStackDeprecationWarning`, `RemovedInSDK50Warning`, `RemovedInSDK60Warning`) to signal deprecated features, resources, or behavior. By default, `DeprecationWarning` messages are silenced in Python.fixEnable Python's deprecation warnings during development and testing using the `-Wa` command-line option (`python -Wa your_script.py`) or by setting the `PYTHONWARNINGS` environment variable (e.g., `export PYTHONWARNINGS=default`). This helps identify code that needs updating before deprecated features are removed.
affects: All versions
Errors
Common errors & fixes
Authentication failed
This error, often accompanied by 'The request you have made requires authentication. (HTTP 401)', indicates that the OpenStack SDK could not successfully authenticate with the Keystone identity service due to incorrect or missing credentials in `clouds.yaml` or environment variables (e.g., `OS_AUTH_URL`, `OS_USERNAME`, `OS_PASSWORD`).
fixEnsure your `clouds.yaml` file is correctly configured with all necessary authentication parameters (auth_url, username, password, project_name, etc.), or that the corresponding `OS_*` environment variables are properly set and sourced. Double-check for typos, extra quotes, or unescaped special characters in passwords, especially when setting environment variables.
ModuleNotFoundError: No module named 'openstack'
This error occurs when the `openstacksdk` library is not installed in the Python environment being used, or the Python interpreter cannot find the installed package.
fixInstall the `openstacksdk` package using pip: `pip install openstacksdk`. If using a virtual environment, ensure it's activated before installation. If the error persists, verify the Python interpreter configured in your IDE or used by your script matches the one where the package was installed.
No cloud named '<your_cloud_name>'
This error arises when `openstack.connect(cloud='<your_cloud_name>')` is called with a cloud name that is not defined in the `clouds.yaml` configuration file, or the `clouds.yaml` file itself is not found in one of the expected locations (e.g., `~/.config/openstack/`, `./`).
fixVerify that `clouds.yaml` exists in an accessible location and that the `cloud` parameter in `openstack.connect()` exactly matches a cloud entry in the `clouds.yaml` file. If using environment variables, use `cloud='envvars'` in `openstack.connect()` or ensure `OS_CLOUD` is set.
AttributeError: module 'openstack.proxy' has no attribute 'Proxy'
This `AttributeError` often occurs when older OpenStack client libraries or specific OpenStack components (like `nova-manage`) attempt to access internal `openstacksdk` attributes or classes (`openstack.proxy.Proxy`) that have been refactored, moved, or removed in newer versions of `openstacksdk`. This typically indicates an incompatibility between different installed OpenStack Python packages or a change in the SDK's internal structure.
fixThis issue often requires ensuring all OpenStack-related Python packages (e.g., `openstacksdk`, `python-openstackclient`, `python-novaclient`) are compatible and up-to-date with each other. If using a specific tool or older client, consult its documentation for `openstacksdk` version requirements. In some cases, it might involve upgrading `openstacksdk` and related clients: `pip install --upgrade openstacksdk python-openstackclient`.
Upgrade
Version history
4.19.1latest on PyPI · released Aug 27, 2026
Audit
Dependencies
keystoneauth1requiredUsed for authentication and HTTP interactions.
os-client-configrequiredFor handling cloud configuration files (clouds.yaml) and environment variables.