Install & Compatibility
Where this runs
tested against v10.4.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.432s · 36.4MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 3.2s · import 0.394s · 38MB
38MB installed
● package 38MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
cfg
✓ from oslo_config import cfg
The primary configuration object is conventionally named `cfg.CONF` after import.
This quickstart demonstrates how to define configuration options, register them (both globally and within groups), and then parse values from a simulated configuration file and command-line arguments. It highlights the explicit parsing step required for oslo.config to load settings from external sources. The example also shows how to access the parsed configuration values.
import sys
from oslo_config import cfg
import os
# Define a configuration group and options
CONF = cfg.CONF
common_opts = [
cfg.StrOpt('bind_host', default='0.0.0.0', help='IP address to listen on'),
cfg.IntOpt('bind_port', default=8080, help='Port to listen on'),
cfg.BoolOpt('debug', default=False, help='Enable debug logging')
]
# Register options
CONF.register_opts(common_opts, group='DEFAULT')
# You can also register options in a specific group
api_group = cfg.OptGroup(name='api', title='API Options')
CONF.register_group(api_group)
api_opts = [
cfg.StrOpt('url', default='http://localhost:8080', help='Base URL for the API'),
cfg.IntOpt('timeout', default=30, help='API request timeout in seconds')
]
CONF.register_opts(api_opts, group=api_group)
# Example config file content (save as 'app.conf')
# [DEFAULT]
# bind_host = 127.0.0.1
# debug = True
#
# [api]
# url = https://api.example.com
# Parse command line arguments and config files
# For testing, we simulate args and a config file
# In a real app, you'd use: CONF(sys.argv[1:], project='myproject', default_config_files=['/etc/myproject/app.conf'])
# Create a dummy config file for demonstration
config_file_path = 'app.conf'
with open(config_file_path, 'w') as f:
f.write('[DEFAULT]\n')
f.write('bind_host = 127.0.0.1\n')
f.write('debug = True\n')
f.write('\n[api]\n')
f.write('url = https://api.example.com\n')
# Simulate CLI args (e.g., --debug=false --api-timeout=60)
sys_args = ['program_name', '--config-file', config_file_path, '--api-timeout', '60']
# oslo.config needs to be explicitly parsed. The first argument is the program name.
# We use os.environ.get for security (e.g., if a secret was passed as an env var)
CONF(args=sys_args[1:], project='myproject')
print(f"Bind Host: {CONF.bind_host}")
print(f"Bind Port: {CONF.bind_port}")
print(f"Debug Mode: {CONF.debug}")
print(f"API URL: {CONF.api.url}")
print(f"API Timeout: {CONF.api.timeout}")
# Clean up the dummy config file
os.remove(config_file_path)
oslo-config-generator --version
Debug
Known issues
gotchaConfiguration sources have a strict precedence: Command-line arguments > Environment variables > Configuration files > Default values. Values from higher precedence sources will override lower ones.fixAlways remember the order of precedence when troubleshooting unexpected configuration values. Verify command-line arguments first, then environment variables, then configuration files.
affects: All versions
gotchaoslo.config requires explicit parsing via `cfg.CONF()` to load values from command-line arguments or configuration files. If not called, only default values for registered options will be active.fixEnsure `cfg.CONF(args=sys.argv[1:], ...)` is called early in your application's startup process to process command-line arguments and load configuration files.
affects: All versions
gotchaWhen integrating with `oslo.log`, be aware of the distinction between `logging_default_format_string` and `logging_context_format_string`. Changes to one may not affect log lines using the other if an `oslo.context` object is attached.fixIf logging format changes aren't taking effect, check which format string is relevant to your log messages. Use `cfg.CONF.set_override()` or a configuration file to adjust both if needed.
affects: All versions (especially when using oslo.log)
gotchaWhile `oslo.config` (version 9.0.0 and newer) supports environment variables as a configuration source via predictable naming conventions (e.g., `OS_MYAPP__GROUP_OPTIONNAME`), older versions might not, or require manual `os.environ` checks.fixFor versions prior to 9.0.0, explicitly use `os.environ.get('ENV_VAR_NAME', default_value)` for environment-based configuration. For newer versions, ensure environment variables follow the `OS_PROJECT__GROUP_OPTIONNAME` pattern to be automatically picked up. affects: <9.0.0
Errors
Common errors & fixes
ImportError: No module named oslo_config.cfg
The `oslo.config` library or its `cfg` module is not correctly installed, not in the Python path, or an incorrect import statement is used (e.g., trying to import `oslo_config.cfg` directly instead of `from oslo_config import cfg`).
fixEnsure the `oslo.config` package is installed using `pip install oslo.config` and use `from oslo_config import cfg` in your Python code.
oslo_config.cfg.NoSuchOptError: no such option <option_name> in group [DEFAULT]
This error occurs when your code attempts to access a configuration option using `cfg.CONF.<option_name>` that has not been registered with `cfg.CONF` or does not exist within the specified configuration group.
fixRegister the option using `cfg.CONF.register_opt()` or `cfg.CONF.register_opts()` before attempting to access it. Ensure the option name and group you are trying to access match the registered definition.
oslo_config.cfg.DuplicateOptError: duplicate option: <option_name>
The application tried to register a configuration option with the same name more than once with `cfg.CONF`, leading to a conflict.
fixEnsure that each `cfg.Opt` (or its subclass like `StrOpt`, `IntOpt`, etc.) is registered only once, typically during the application's initialization phase. Review your code for multiple `register_opt` or `register_opts` calls for the same option name.
oslo_config.cfg.RequiredOptError: value required for option <option_name> in group [DEFAULT]
A configuration option was defined with `required=True`, but no value was supplied for it through any of the configuration sources (command-line arguments, environment variables, or configuration files).
fixProvide a value for the required option in a configuration file, as an environment variable, or as a command-line argument. Alternatively, if the option is not strictly mandatory, remove the `required=True` parameter from its definition or provide a `default` value during registration.
oslo_config.cfg.ConfigFileParseError: Failed to parse config file: <file_path>
The configuration file specified by the application contains syntax errors or is malformed, preventing `oslo-config` from correctly interpreting its contents.
fixExamine the specified configuration file (typically an INI-style file) for any syntax errors, such as incorrect section headers (`[group]`), malformed key-value pairs (`key = value`), or unescaped characters. Ensure it adheres to the standard INI file format.
Upgrade
Version history
10.7.0latest on PyPI · released Aug 7, 2026
Audit
Dependencies
oslo.logrequiredCommonly used alongside oslo.config for unified logging configuration within OpenStack projects.
oslo.i18noptionalUsed for internationalization and localization of messages and help strings within configuration options.
stevedoreoptionalUsed for managing extensible components and drivers, which oslo.config can leverage for configuration sources.
debtcollectoroptionalA utility library used by Oslo projects for managing deprecated code paths.