Install & Compatibility
Where this runs
tested against v2.7.1 · 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.920 runs
installs and imports cleanly · install 0.0s · import 0.482s · 50.1MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 4.8s · import 0.473s · 52MB
52MB installed
● package 52MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
UpgradeCommands
✓ from oslo_upgradecheck.upgradecheck import UpgradeCommands
✗ from oslo.upgradecheck import UpgradeCommands
The official import uses `oslo_upgradecheck` as the top-level package, not `oslo.upgradecheck` (which is a common pattern for older OpenStack 'oslo' projects that were not PEP 420 namespace packages).
check_func
✓ from oslo_upgradecheck.upgradecheck import check_func
This quickstart demonstrates how to define custom upgrade checks using the `oslo_upgradecheck.check_func` decorator and run them using `UpgradeCommands`. Each check function should return a tuple of `(status, details)`, where `status` is a boolean indicating success/failure and `details` is a string message. The `group` argument in `check_func` allows organizing checks into different phases (e.g., pre-upgrade, post-upgrade).
import sys
from oslo_upgradecheck.upgradecheck import UpgradeCommands, check_func
@check_func(group='required_pre_upgrade')
def my_first_check():
"""This is my first upgrade check.
:returns: a tuple of (status, details).
"""
# Simulate a successful check
return (True, "My service is ready for upgrade.")
@check_func(group='required_pre_upgrade')
def my_second_check():
"""This is my second, more complex check.
:returns: a tuple of (status, details).
""
# Simulate a failed check based on some condition
is_database_migrated = False # In a real scenario, check DB status
if not is_database_migrated:
return (False, "Database migration is incomplete. Please run 'db sync'.")
return (True, "Database is migrated.")
def main():
# In a real OpenStack project, oslo_config would be initialized here
# to handle command-line arguments and configuration.
# For this quickstart, we'll manually invoke the checks.
commands = UpgradeCommands()
# You can specify which group of checks to run
# e.g., 'required_pre_upgrade', 'pre_upgrade', 'post_upgrade'
print("\n--- Running required_pre_upgrade checks ---")
results = commands.run_checks(group='required_pre_upgrade')
for check, status, details in results:
print(f"Check: {check.__name__}, Status: {status}, Details: {details}")
if any(not s for _, s, _ in results):
print("\nSome required checks failed. Upgrade is not recommended.")
sys.exit(1)
else:
print("\nAll required checks passed. Proceed with upgrade.")
sys.exit(0)
if __name__ == '__main__':
main()
oslo-upgradecheck --version
Debug
Known issues
breakingAs part of the wider OpenStack project, oslo-upgradecheck and other oslo libraries have dropped support for Python 2.7. Users must use Python 3.10 or newer, as specified in PyPI metadata.fixEnsure your environment uses Python >=3.10. Upgrade your Python interpreter if necessary.
affects: <=2.x (pre-Python 3.10 requirement)
gotchaWhen integrating `oslo-upgradecheck` into an OpenStack service, it's crucial to properly initialize `oslo.config` before running checks. Failure to do so can lead to `oslo_config.cfg.NotInitializedError` when checks attempt to access configuration options.fixEnsure `oslo_config.cfg.CONF()` (or a similar initialization) is called and configuration files are loaded before invoking `UpgradeCommands.run_checks()`.
affects: All versions
deprecatedOlder versions of `oslo-upgradecheck` (prior to 0.3.0, Train series) only output human-readable tables. Newer versions support a `--json` flag for machine-readable output.fixFor machine-readable output, upgrade to `oslo-upgradecheck` version 0.3.0 or later and use the `--json` command-line flag.
affects: <0.3.0
Errors
Common errors & fixes
oslo_config.cfg.NotInitializedError: call expression on parser has not been invoked.
`oslo.config`'s configuration parser was not properly initialized or loaded before an `oslo-upgradecheck` function attempted to access a configuration option.
fixEnsure that `oslo_config.cfg.CONF()` is called at the application's entry point, and that relevant configuration files are loaded using `cfg.CONF(args=[])` or `cfg.CONF.register_opts()` as appropriate for your service. This often happens in a `main()` function or similar setup block.
ImportError: No module named oslo_upgradecheck
The `oslo-upgradecheck` library is not installed in the current Python environment.
fixRun `pip install oslo-upgradecheck` to install the package.
Upgrade
Version history
2.7.1latest on PyPI · released Feb 17, 2026
Audit
Dependencies
oslo.configrequiredRequired for configuration management within OpenStack projects, often used by upgrade checks.
oslo.utilsrequiredProvides various utility functions commonly used across Oslo libraries and OpenStack projects.
oslo.i18noptionalUsed for internationalization and localization support.
oslo.policyoptionalFor RBAC policy enforcement, which may be part of some upgrade checks.