Install & Compatibility
Where this runs
No compatibility data collected yet for this library.
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
openstack
✓ import subprocess
# ... or use openstacksdk for direct Python API interaction
✗ from openstackclient import Client
`python-openstackclient` is primarily a command-line interface. Direct programmatic import of the `openstackclient` module for application logic is not the typical pattern. For Python API interactions, the `openstacksdk` library is recommended. If you need to execute CLI commands from Python, use `subprocess`.
This quickstart demonstrates how to interact with the OpenStack CLI programmatically from Python using `subprocess`. It shows two common authentication methods: environment variables (often sourced from an `openrc` file) and `clouds.yaml`. Ensure your OpenStack credentials are set as environment variables or configured in a `clouds.yaml` file for the client to authenticate successfully.
import os
import subprocess
# --- Configuration (choose one method) ---
# Method 1: Environment Variables (recommended for scripts)
os.environ['OS_AUTH_URL'] = os.environ.get('OS_AUTH_URL', 'http://<your-keystone-url>/v3')
os.environ['OS_USERNAME'] = os.environ.get('OS_USERNAME', 'admin')
os.environ['OS_PASSWORD'] = os.environ.get('OS_PASSWORD', 'your_password')
os.environ['OS_PROJECT_NAME'] = os.environ.get('OS_PROJECT_NAME', 'admin')
os.environ['OS_USER_DOMAIN_NAME'] = os.environ.get('OS_USER_DOMAIN_NAME', 'Default')
os.environ['OS_PROJECT_DOMAIN_NAME'] = os.environ.get('OS_PROJECT_DOMAIN_NAME', 'Default')
os.environ['OS_IDENTITY_API_VERSION'] = os.environ.get('OS_IDENTITY_API_VERSION', '3')
# Method 2: clouds.yaml (often found in ~/.config/openstack/clouds.yaml)
# Ensure your clouds.yaml is configured and replace 'my-cloud' with your cloud name
# If using clouds.yaml, you might not need to set environment variables.
# Example clouds.yaml content (place in ~/.config/openstack/clouds.yaml or specify via OS_CLIENT_CONFIG_FILE):
# clouds:
# my-cloud:
# auth:
# auth_url: 'http://<your-keystone-url>/v3'
# username: 'admin'
# password: 'your_password'
# project_name: 'admin'
# user_domain_name: 'Default'
# project_domain_name: 'Default'
# region_name: 'RegionOne'
# Example: List OpenStack projects using the CLI
try:
print("\n--- Listing OpenStack Projects ---")
# Use 'openstack --os-cloud my-cloud project list' if using clouds.yaml
result = subprocess.run(['openstack', 'project', 'list'], capture_output=True, text=True, check=True)
print(result.stdout)
if result.stderr:
print("Stderr:\n", result.stderr)
print("\n--- Listing OpenStack Services ---")
result = subprocess.run(['openstack', 'service', 'list'], capture_output=True, text=True, check=True)
print(result.stdout)
if result.stderr:
print("Stderr:\n", result.stderr)
except subprocess.CalledProcessError as e:
print(f"Error executing OpenStack CLI command: {e.cmd}")
print(f"Return Code: {e.returncode}")
print(f"Stdout:\n{e.stdout}")
print(f"Stderr:\n{e.stderr}")
except FileNotFoundError:
print("Error: 'openstack' command not found. Is OpenStackClient installed and in your PATH?")
openstack --version
Debug
Known issues
breakingPython 2.x is no longer supported. `python-openstackclient` 9.0.0 requires Python >=3.10. Older versions of the client (especially pre-3.x) might have exhibited syntax errors if run with Python 2.fixEnsure your environment uses Python 3.10 or higher. Use `python3 -m pip install ...`.
affects: <9.0.0
gotchaThere are two PyPI packages: `python-openstackclient` (the core client) and `openstackclient` (a metapackage that installs `python-openstackclient` and common plugins). The latter is often recommended for a more complete experience.fixFor a full suite of commands, `pip install openstackclient` is generally preferred.
affects: All versions
deprecatedLegacy project-specific command-line clients (e.g., `nova`, `glance`, `cinder` CLIs) are being actively superseded by `python-openstackclient` for a unified experience. Some advanced or less common features might still exist only in the legacy clients but are being migrated.fixPrefer using `openstack <service> <command>` (e.g., `openstack server list`) over legacy commands (e.g., `nova list`). Refer to documentation for equivalent commands.
affects: All versions (ongoing transition)
gotchaInstalling Python packages directly into the system's Python environment using `pip install` without a virtual environment can lead to conflicts and break system tools.fixAlways use Python virtual environments (`python3 -m venv .venv` and `source .venv/bin/activate`) when installing packages with `pip` to isolate dependencies.
affects: All versions
gotchaAuthentication can be configured via environment variables (e.g., sourcing an `openrc` file), a `clouds.yaml` file, or command-line options. Inconsistent or missing authentication details are a common source of errors.fixEnsure one of the authentication methods is correctly configured. For `clouds.yaml`, it's typically located at `~/.config/openstack/clouds.yaml` or specified via `OS_CLIENT_CONFIG_FILE`. Verify settings like `OS_AUTH_URL`, `OS_USERNAME`, `OS_PASSWORD`, `OS_PROJECT_NAME`, etc.
affects: All versions
Errors
Common errors & fixes
ERROR (Unauthorized): The request you have made requires authentication.
This error indicates that the provided credentials (username, password, or token) are incorrect, expired, or lack the necessary permissions to authenticate with the OpenStack Identity service (Keystone).
fixVerify that your OpenStack environment variables (`OS_AUTH_URL`, `OS_USERNAME`, `OS_PASSWORD`, `OS_PROJECT_NAME`, `OS_REGION_NAME`) or `clouds.yaml` entries are correctly configured and match your OpenStack cloud's authentication requirements.
ERROR (ConnectionRefusedError): Could not connect to host <hostname>:<port>.
This is a network error indicating that the OpenStack API endpoint the client is trying to reach is unreachable, either due to network connectivity issues, an incorrect URL, or the OpenStack service not running.
fixCheck your network connectivity to the OpenStack API endpoint, verify that the `OS_AUTH_URL` environment variable or the endpoint in `clouds.yaml` is correct, and ensure that the OpenStack Identity service (Keystone) is running and accessible.
ERROR (CommandError): You must provide a project or domain to authenticate.
OpenStack authentication often requires a specific project (tenant) or domain scope, and this error occurs when `OS_PROJECT_NAME`, `OS_PROJECT_ID`, `OS_DOMAIN_NAME`, or `OS_DOMAIN_ID` is missing or incorrect in your configuration.
fixSet the `OS_PROJECT_NAME` (or `OS_TENANT_NAME`) and `OS_PROJECT_DOMAIN_NAME` (if applicable) environment variables, or ensure that `project_name` and `project_domain_name` are correctly specified in your `clouds.yaml` configuration.
ERROR (ConfigException): No cloud named 'mycloud' found in clouds.yaml or envvars
This error occurs when the `openstack` command is invoked with `--os-cloud <name>` or the `OS_CLOUD` environment variable is set to a cloud name that does not exist in your `~/.config/openstack/clouds.yaml` file or is not configured via environment variables.
fixVerify that the cloud name specified (e.g., `mycloud`) matches an existing entry in your `clouds.yaml` file, or ensure the `OS_CLOUD` environment variable is correctly set to a valid cloud configuration.
ERROR (DiscoveryFailure): Could not discover appropriate API version
This error indicates that the OpenStackClient failed to discover the available API versions for a service, often due to an incorrect `OS_AUTH_URL` or issues with the service catalog provided by the Identity service (Keystone).
fixVerify that your `OS_AUTH_URL` environment variable points to a valid OpenStack Identity service endpoint, and ensure that the OpenStack services you are trying to access are running and their endpoints are correctly registered in Keystone's service catalog.
Upgrade
Version history
10.3.0latest on PyPI · released Aug 27, 2026
Audit
Dependencies
openstackclientoptionalThe `openstackclient` package is a metapackage that installs `python-openstackclient` and a number of optional plugins, simplifying installation for a full CLI experience.