Install & Compatibility
Where this runs
tested against v4.6.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.194s · 102.7MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 8.8s · import 0.184s · 104MB
110MB installed
● package 110MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Command
✓ from osc_lib.command.command import Command
✗ from openstackclient.common.command import Command
Many core components, including 'Command' and 'Lister', were moved from the 'openstackclient.common' namespace to 'osc_lib.command' after OpenStackClient 2.4.0.
Session
✓ from osc_lib.session import Session
✗ from openstackclient.common.session import Session
Session management utilities were relocated to 'osc_lib.session' for plugin development.
APIClient
✓ from osc_lib.api.api import APIClient
✗ from openstackclient.api.api import APIClient
API interaction utilities moved from 'openstackclient.api' to 'osc_lib.api'.
build_auth_plugins_option_parser
✓ from osc_lib.api.auth import build_auth_plugins_option_parser
✗ from openstackclient.api.auth import build_auth_plugins_option_parser
Authentication-related functions and parsers were moved to 'osc_lib.api.auth'.
backward_compat_col_lister
✓ from osc_lib.utils import backward_compat_col_lister
✗ from openstackclient.common.utils import backward_compat_col_lister
Common utilities, including those for column handling, are now found under 'osc_lib.utils'.
This quickstart demonstrates how to define a custom OpenStackClient command using `osc-lib`. It outlines extending `osc_lib.command.command.Command` to create a new CLI action, including argument parsing and action execution. Note that `osc-lib` is primarily for building plugins, so this code requires an OpenStackClient environment to run fully, but the example shows the core structure for plugin development. The `MockApp` and `MockAppArgs` classes are included to make the example runnable for demonstrating the `take_action` logic, though they don't replicate a full OpenStackClient runtime environment.
import argparse
from osc_lib.command.command import Command
class MyCustomCommand(Command):
"""My custom OpenStackClient command."""
def get_parser(self, prog_name):
parser = super(MyCustomCommand, self).get_parser(prog_name)
parser.add_argument(
'name',
metavar='<name>',
help='Name to greet'
)
return parser
def take_action(self, parsed_args):
# In a real OpenStackClient plugin, 'self.app' and 'self.client_manager'
# would provide access to OpenStack services and configuration.
# For this example, we'll simulate the output.
greeting = f"Hello, {parsed_args.name}! This is a custom command from osc-lib."
return {}, {'Result': greeting}
# Example of how to instantiate and call (for demonstration, not runnable without OSC context)
if __name__ == '__main__':
# Simulate `app` and `app_args` that `cliff` (which OSC uses) would pass
class MockApp:
NAME = 'openstack'
def __init__(self):
self.options = argparse.Namespace()
self.options.debug = False
class MockAppArgs:
pass
mock_app = MockApp()
mock_app_args = MockAppArgs()
cmd_instance = MyCustomCommand(mock_app, mock_app_args)
# Simulate parsed arguments
parsed_args = cmd_instance.get_parser('my_command').parse_args(['World'])
# Execute the command's action
# In a real setup, this would be called by the OpenStackClient framework
_columns, _data = cmd_instance.take_action(parsed_args)
print(f"Command output: {_data['Result']}")
Debug
Known issues
breakingMany core modules and classes, such as `Command`, `Session`, and API utilities, were relocated from the `openstackclient.*` namespace to `osc_lib.*` after OpenStackClient 2.4.0. Direct imports from the old `openstackclient` paths for these components will cause `ImportError` or unexpected behavior in newer versions of `osc-lib`.fixUpdate import statements from `openstackclient.api.api`, `openstackclient.api.auth`, `openstackclient.common.command`, `openstackclient.common.commandmanager`, `openstackclient.common.exceptions`, `openstackclient.common.logs`, `openstackclient.common.session`, `openstackclient.common.utils`, etc., to their corresponding `osc_lib` paths, e.g., `from osc_lib.command.command import Command`.
affects: Post OpenStackClient 2.4.0 and all `osc-lib` versions.
gotcha`osc-lib` is a library for developing plugins and extensions for the OpenStackClient, not a standalone client for direct interaction with OpenStack APIs. Attempting to use `osc-lib` directly as a full client without the OpenStackClient framework will lead to missing dependencies and incorrect usage patterns.fixUtilize `osc-lib` components within the context of an OpenStackClient plugin. For direct OpenStack API interaction, use the `openstacksdk` library.
affects: All versions
deprecatedThe `osc_lib.utils.backward_compat_col_lister` function explicitly logs warnings when older, deprecated column names are used in CLI output. While the function provides backward compatibility, relying on deprecated column names for parsing or display in plugins may lead to future breakage once full support is removed.fixReview and update plugin code to use the current, recommended column names as defined by OpenStackClient and its services, rather than relying on backward-compatible names. Monitor `osc-lib` release notes for details on specific column deprecations.
affects: Versions with `osc_lib.utils.backward_compat_col_lister` (e.g., 4.x.x)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'openstackclient.common.command'
This error occurs because many common modules previously residing under `openstackclient.common` were extracted into the separate `osc-lib` library after `OpenStackClient` version 2.4.0. Older plugins or codebases might still use the deprecated import paths.
fixUpdate your import statements to use `osc_lib` instead of `openstackclient.common`. For example, change `from openstackclient.common import command` to `from osc_lib import command`.
ModuleNotFoundError: No module named 'osc_lib'
This error indicates that the `osc-lib` package is not installed in your Python environment or that your current Python interpreter cannot locate the installed package.
fixInstall `osc-lib` using pip: `pip install osc-lib`. If using a virtual environment, ensure it is activated before installation.
AttributeError: 'ClientManager' object has no attribute 'some_method'
This `AttributeError` typically arises when attempting to access a method or attribute on an `osc_lib` object, such as `ClientManager`, that either does not exist in the installed version of `osc-lib` or has been renamed/refactored in a newer release. It can also occur if the object is not correctly initialized or the plugin expects an older API signature.
fixConsult the official `osc-lib` documentation for the specific version you are using to verify the correct API methods and their usage. Update your code to align with the current `osc-lib` API.
Upgrade
Version history
4.7.0latest on PyPI · released Jul 10, 2026
Audit
Dependencies
No dependency data recorded yet.