Install & Compatibility
Where this runs
tested against v6.0.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 0.596s · 50MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 5.0s · import 0.568s · 52MB
54MB installed
● package 54MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
v3.Password
✓ from keystoneauth1.identity import v3
session.Session
✓ from keystoneauth1 import session
client.Client
✓ from keystoneclient.v3 import client
keystoneclient.exceptions.ClientException
✓ from keystoneclient import exceptions
✗ from keystoneclient.apiclient import exceptions
The keystoneclient.apiclient.exceptions module was removed in version 2.1.0; exceptions are now mapped to keystoneauth1.exceptions.
This quickstart demonstrates how to authenticate with OpenStack Keystone using the V3 API and session-based authentication, then lists available projects. It leverages environment variables for credentials, which is a common and secure practice in OpenStack environments.
import os
from keystoneauth1.identity import v3
from keystoneauth1 import session
from keystoneclient.v3 import client
# Environment variables for authentication (recommended practice)
AUTH_URL = os.environ.get('OS_AUTH_URL', 'http://localhost:5000/v3')
USERNAME = os.environ.get('OS_USERNAME', 'admin')
PASSWORD = os.environ.get('OS_PASSWORD', 'password')
PROJECT_NAME = os.environ.get('OS_PROJECT_NAME', 'admin')
USER_DOMAIN_ID = os.environ.get('OS_USER_DOMAIN_ID', 'default')
PROJECT_DOMAIN_ID = os.environ.get('OS_PROJECT_DOMAIN_ID', 'default')
# 1. Authenticate using a session (V3 API example)
auth = v3.Password(
auth_url=AUTH_URL,
username=USERNAME,
password=PASSWORD,
project_name=PROJECT_NAME,
user_domain_id=USER_DOMAIN_ID,
project_domain_id=PROJECT_DOMAIN_ID
)
sess = session.Session(auth=auth)
# 2. Initialize the Keystone client
keystone = client.Client(session=sess)
# 3. Perform an operation (e.g., list projects)
try:
projects = keystone.projects.list()
print(f"Successfully connected to Keystone. Found {len(projects)} projects.")
for project in projects:
print(f" - {project.name} (ID: {project.id})")
except exceptions.ClientException as e:
print(f"Error connecting to Keystone: {e}")
except Exception as e:
print(f"An unexpected error occurred: {e}")
openstack --version
Debug
Known issues
deprecatedThe `keystone` command-line interface (CLI) is deprecated in favor of the `openstack` CLI provided by `python-openstackclient`.fixMigrate CLI operations to `python-openstackclient`. Install it via `pip install python-openstackclient` and use `openstack <service> <command>` instead (e.g., `openstack user list`).
affects: All versions since OpenStack Kilo (approx. 2015) onwards.
deprecatedNon-session based authentication (passing username, password directly to `keystoneclient.Client` without a `keystoneauth1.session.Session` object) is deprecated.fixAlways use `keystoneauth1.session.Session` with an authentication plugin (e.g., `keystoneauth1.identity.v3.Password`) and pass the session to the `keystoneclient.Client` constructor. This provides more robust and flexible authentication.
affects: All versions since at least 5.x. Earlier versions also recommended session-based auth.
deprecated`keystoneclient` authentication plugins are deprecated in favor of `keystoneauth1` plugins.fixEnsure you are using authentication plugins directly from the `keystoneauth1.identity` module, not `keystoneclient.auth.identity`.
affects: Since version 2.1.0.
breakingThe exception classes previously found under `keystoneclient.apiclient.exceptions` were removed and mapped to `keystoneauth1.exceptions`. Direct imports from `keystoneclient.apiclient.exceptions` will fail.fixUpdate import statements to use `from keystoneclient import exceptions` and refer to the appropriate exception classes (which are aliases to `keystoneauth1` exceptions).
affects: 2.1.0 and later.
gotchaWhen bundling applications with PyInstaller, `python-keystoneclient` (and its dependency `keystoneauth1`) may encounter `PackageNotFoundError` or issues related to `pbr` versioning.fixProvide explicit hidden imports and copy metadata for `keystoneclient`, `keystoneauth1`, and `os_service_types` in your PyInstaller `.spec` file. Example additions to `hiddenimports` and `added_files` can be found in Stack Overflow solutions.
affects: All versions.
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'keystoneclient'
The `python-keystoneclient` library is not installed in the current Python environment.
fixpip install python-keystoneclient
keystoneclient.exceptions.Unauthorized: The request you have made requires authentication. (HTTP 401)
Incorrect authentication credentials (username, password, project, domain), wrong authentication URL, or an expired token.
fixVerify `OS_AUTH_URL`, `OS_USERNAME`, `OS_PASSWORD`, `OS_PROJECT_NAME` (or `OS_PROJECT_ID`), and `OS_USER_DOMAIN_NAME` environment variables or client parameters.
keystoneauth1.exceptions.discovery.DiscoveryFailure: Could not determine appropriate URL for authentication.
The `OS_AUTH_URL` environment variable is not set or is incorrect, preventing the client from finding the Keystone authentication endpoint.
fixEnsure the `OS_AUTH_URL` environment variable is correctly set and points to your Keystone authentication endpoint.
AttributeError: 'NoneType' object has no attribute 'get_token'
The `keystoneauth1` session object failed to authenticate and obtain a valid token from Keystone, often due to incorrect credentials or an unreachable auth URL.
fixCheck all authentication parameters (e.g., `OS_AUTH_URL`, `OS_USERNAME`, `OS_PASSWORD`) to ensure the `keystoneauth1` session can successfully obtain a token.
Upgrade
Version history
6.0.0latest on PyPI · released Aug 28, 2026
Audit
Dependencies
keystoneauth1requiredProvides authentication plugins and session management, which python-keystoneclient leverages.