{"id":4162,"library":"oslo-config","title":"Oslo Configuration API","description":"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.","status":"active","version":"10.3.0","language":"python","source_language":"en","source_url":"https://github.com/openstack/oslo.config","tags":["OpenStack","configuration","CLI","INI files","settings","config-parsing"],"install":[{"cmd":"pip install oslo.config","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Commonly used alongside oslo.config for unified logging configuration within OpenStack projects.","package":"oslo.log","optional":false},{"reason":"Used for internationalization and localization of messages and help strings within configuration options.","package":"oslo.i18n","optional":true},{"reason":"Used for managing extensible components and drivers, which oslo.config can leverage for configuration sources.","package":"stevedore","optional":true},{"reason":"A utility library used by Oslo projects for managing deprecated code paths.","package":"debtcollector","optional":true}],"imports":[{"note":"The primary configuration object is conventionally named `cfg.CONF` after import.","symbol":"cfg","correct":"from oslo_config import cfg"}],"quickstart":{"code":"import sys\nfrom oslo_config import cfg\nimport os\n\n# Define a configuration group and options\nCONF = cfg.CONF\ncommon_opts = [\n    cfg.StrOpt('bind_host', default='0.0.0.0', help='IP address to listen on'),\n    cfg.IntOpt('bind_port', default=8080, help='Port to listen on'),\n    cfg.BoolOpt('debug', default=False, help='Enable debug logging')\n]\n\n# Register options\nCONF.register_opts(common_opts, group='DEFAULT')\n\n# You can also register options in a specific group\napi_group = cfg.OptGroup(name='api', title='API Options')\nCONF.register_group(api_group)\napi_opts = [\n    cfg.StrOpt('url', default='http://localhost:8080', help='Base URL for the API'),\n    cfg.IntOpt('timeout', default=30, help='API request timeout in seconds')\n]\nCONF.register_opts(api_opts, group=api_group)\n\n# Example config file content (save as 'app.conf')\n# [DEFAULT]\n# bind_host = 127.0.0.1\n# debug = True\n#\n# [api]\n# url = https://api.example.com\n\n# Parse command line arguments and config files\n# For testing, we simulate args and a config file\n# In a real app, you'd use: CONF(sys.argv[1:], project='myproject', default_config_files=['/etc/myproject/app.conf'])\n\n# Create a dummy config file for demonstration\nconfig_file_path = 'app.conf'\nwith open(config_file_path, 'w') as f:\n    f.write('[DEFAULT]\\n')\n    f.write('bind_host = 127.0.0.1\\n')\n    f.write('debug = True\\n')\n    f.write('\\n[api]\\n')\n    f.write('url = https://api.example.com\\n')\n\n# Simulate CLI args (e.g., --debug=false --api-timeout=60)\nsys_args = ['program_name', '--config-file', config_file_path, '--api-timeout', '60']\n\n# oslo.config needs to be explicitly parsed. The first argument is the program name.\n# We use os.environ.get for security (e.g., if a secret was passed as an env var)\nCONF(args=sys_args[1:], project='myproject')\n\nprint(f\"Bind Host: {CONF.bind_host}\")\nprint(f\"Bind Port: {CONF.bind_port}\")\nprint(f\"Debug Mode: {CONF.debug}\")\nprint(f\"API URL: {CONF.api.url}\")\nprint(f\"API Timeout: {CONF.api.timeout}\")\n\n# Clean up the dummy config file\nos.remove(config_file_path)\n","lang":"python","description":"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."},"warnings":[{"fix":"Always remember the order of precedence when troubleshooting unexpected configuration values. Verify command-line arguments first, then environment variables, then configuration files.","message":"Configuration sources have a strict precedence: Command-line arguments > Environment variables > Configuration files > Default values. Values from higher precedence sources will override lower ones.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"oslo.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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"When 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.","severity":"gotcha","affected_versions":"All versions (especially when using oslo.log)"},{"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.","message":"While `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.","severity":"gotcha","affected_versions":"<9.0.0"}],"env_vars":null,"search_vec":"'10.3.0':74 'activ':79 'api':3,17 'applic':46 'argument':23,64 'cadenc':81 'cli':90 'command':21,62 'command-lin':20,61 'compon':34 'config':95 'config-pars':94 'configur':2,28,52,56,89 'current':71 'cycl':87 'default':55 'defin':67 'develop':86 'environ':58 'file':29,57,92 'flexibl':42 'fundament':33 'includ':54 'ini':26,91 'ini-styl':25 'librari':8,49 'line':22,63 'maintain':77 'manag':45 'multipl':51 'offer':38 'openstack':11,36,85,88 'order':69 'oslo':1 'oslo.config':4 'pars':19,96 'preced':68 'project':12 'provid':14 'python':7 'releas':80 'robust':16 'servic':37 'set':47,93 'sourc':53 'style':27 'support':50 'tie':82 'unifi':40 'variabl':59 'version':72 'way':43","created_at":"2026-04-12T03:43:36.764242+00:00","updated_at":"2026-04-16T17:49:22.613136+00:00","problems":[{"fix":"Ensure the `oslo.config` package is installed using `pip install oslo.config` and use `from oslo_config import cfg` in your Python code.","cause":"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`).","error":"ImportError: No module named oslo_config.cfg"},{"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.","cause":"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.","error":"oslo_config.cfg.NoSuchOptError: no such option <option_name> in group [DEFAULT]"},{"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.","cause":"The application tried to register a configuration option with the same name more than once with `cfg.CONF`, leading to a conflict.","error":"oslo_config.cfg.DuplicateOptError: duplicate option: <option_name>"},{"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.","cause":"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).","error":"oslo_config.cfg.RequiredOptError: value required for option <option_name> in group [DEFAULT]"},{"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.","cause":"The configuration file specified by the application contains syntax errors or is malformed, preventing `oslo-config` from correctly interpreting its contents.","error":"oslo_config.cfg.ConfigFileParseError: Failed to parse config file: <file_path>"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"10.7.0","cli_name":"oslo-config-generator","cli_version":"10.3.0","type":"library","homepage":"https://docs.openstack.org/oslo.config","github":null,"docs":null,"changelog":null,"pypi":"https://pypi.org/project/oslo-config/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["devops","serialization","workflow"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-29","next_check":"2026-07-28","install_tag":null}}