Registry / devops / oslo-config

oslo-config

JSON →
library10.7.0pypypi✓ verified 22d ago

Oslo.config is a Python library from the OpenStack project that provides a robust API for parsing command-line arguments and .ini-style configuration files. It's a fundamental component for OpenStack services, offering a unified and flexible way to manage application settings. The library supports multiple configuration sources, including defaults, configuration files, environment variables, and command-line arguments, with a defined precedence order. The current version is 10.3.0, and it maintains an active release cadence tied to the OpenStack development cycle.

pip install oslo.config
INSTALL
IMPORT
SIG · OSLO-CONFIG
O
oslo-config
devopspythonv10.7.0
Install
3.2s avg
Import
413ms
Disk
38MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
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
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.432s · 36.4MB
glibc
py 3.103.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.
fix
Always 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.
fix
Ensure `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.
fix
If 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.
fix
For 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`).
fix
Ensure 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.
fix
Register 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.
fix
Ensure 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).
fix
Provide 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.
fix
Examine 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.
Agent activity
25 hits · last 30 days
node
22
OpenAI (training)
1
Resources
oslo-config — pip install oslo-config · libregistry