{"id":842,"library":"click-option-group","title":"Click Option Group","description":"click-option-group is a Click-extension package that provides the functionality for creating option groups in Click-based command-line interfaces. It allows for logical structuring of CLI options and defining specific behaviors and relationships among grouped options, such as mutually exclusive or required option sets. The package is actively maintained, with its current version being 0.5.9, and receives regular updates.","status":"active","version":"0.5.9","language":"python","source_language":"en","source_url":"https://github.com/click-contrib/click-option-group","tags":["click","cli","options","command-line-interface","decorators","option-groups"],"install":[{"cmd":"pip install click-option-group","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core dependency as it's a Click extension.","package":"click","optional":false}],"imports":[{"note":"The primary decorator for defining option groups and options within them.","symbol":"optgroup","correct":"from click_option_group import optgroup"},{"note":"Used to define groups where at least one option must be set.","symbol":"RequiredAnyOptionGroup","correct":"from click_option_group import RequiredAnyOptionGroup"},{"note":"Used to define groups where all options must be set, or none must be set.","symbol":"AllOptionGroup","correct":"from click_option_group import AllOptionGroup"},{"note":"Used to define groups where all options must be set.","symbol":"RequiredAllOptionGroup","correct":"from click_option_group import RequiredAllOptionGroup"},{"note":"Used to define groups where only one or none of the options must be set.","symbol":"MutuallyExclusiveOptionGroup","correct":"from click_option_group import MutuallyExclusiveOptionGroup"},{"note":"Used to define groups where exactly one option must be set.","symbol":"RequiredMutuallyExclusiveOptionGroup","correct":"from click_option_group import RequiredMutuallyExclusiveOptionGroup"}],"quickstart":{"code":"import click\nfrom click_option_group import optgroup, RequiredMutuallyExclusiveOptionGroup\n\n@click.command()\n@optgroup.group('Server configuration', help='The configuration of some server connection')\n@optgroup.option('-h', '--host', default='localhost', help='Server host name')\n@optgroup.option('-p', '--port', type=int, default=8888, help='Server port')\n@optgroup.option('-n', '--attempts', type=int, default=3, help='The number of connection attempts')\n@optgroup.option('-t', '--timeout', type=int, default=5, help='The server response timeout')\n@optgroup.group('Input data sources', cls=RequiredMutuallyExclusiveOptionGroup, help='The sources of the input data')\n@optgroup.option('--tsv-file', type=click.Path(), help='CSV/TSV input data file')\n@optgroup.option('--json-file', type=click.Path(), help='JSON input data file')\n@click.option('--debug/--no-debug', default=False, help='Debug flag')\ndef cli(**params):\n    click.echo(f\"Running with parameters: {params}\")\n\nif __name__ == '__main__':\n    cli()","lang":"python","description":"This example demonstrates how to create two option groups: 'Server configuration' with standard options and 'Input data sources' using `RequiredMutuallyExclusiveOptionGroup` to ensure only one file type is provided."},"warnings":[{"fix":"Ensure all optional arguments to `optgroup.group()` or `optgroup()` are passed as keyword arguments (e.g., `optgroup.group('Name', help='Description')`).","message":"As of v0.5.2, all arguments to the `optgroup` decorator, except for `name`, must be passed as keyword-only arguments. Positional arguments for `cls`, `help`, or `attrs` will raise an error.","severity":"breaking","affected_versions":">=0.5.2"},{"fix":"Use `optgroup.option()` for all options within a declared `optgroup`. Do not intersperse with `click.option()` for grouped options.","message":"Mixing `optgroup.option()` and `click.option()` decorators on the same command is not supported and will raise an exception. All options intended to be part of an `optgroup` must use `optgroup.option()`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure your Click installation is version 8.x (e.g., `click<9`). Check the latest `click-option-group` releases for updates on Click 9.x compatibility.","message":"Version `0.5.3` specifically bumped the Click dependency to `<9`, indicating potential incompatibility with Click 9.x and later. Users on Click 9.x may encounter issues.","severity":"compatibility","affected_versions":">=0.5.3 (regarding Click versions >=9.0)"},{"fix":"Define Click arguments using `@click.argument()` decorator outside or above any `@optgroup` decorators.","message":"The `optgroup` decorator does not support `click.argument()` directly. Arguments must be handled separately outside of an option group.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always define an option group using `@optgroup.group()` or `@optgroup()` before declaring options within that group using `@optgroup.option()`.","message":"Calling `optgroup.option()` without a preceding `optgroup.group()` (or `optgroup()`) declaration for the current command will result in an exception.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure that your command-line invocation provides one and only one of the options declared within the mutually exclusive or required option group.","message":"When defining an option group with mutual exclusivity or requiring one of its options, users must provide exactly one of the options from that group. Failure to do so will result in a validation error indicating missing required options.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure that exactly one option from a required and mutually exclusive option group is provided when invoking the command.","message":"When an option group is defined as both `required=True` and `mutually_exclusive=True`, the command will raise an `Error: Missing one of the required mutually exclusive options` if no option from that group is provided by the user.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-05-12T20:18:22.495Z","next_check":"2026-06-27T00:00:00.000Z","problems":[{"fix":"Ensure that all options belonging to an `optgroup.group()` are defined using `@optgroup.option()`. Place any standard Click options using `@click.option()` either before or after the entire `optgroup.group()` block. For example:\n```python\nimport click\nfrom click_option_group import optgroup\n\n@click.command()\n@click.option('--global-param')\n@optgroup.group('My Group')\n@optgroup.option('--foo')\n@optgroup.option('--bar')\ndef cli(global_param, foo, bar):\n    pass\n```","cause":"The `click-option-group` library does not allow mixing `optgroup.option()` and `click.option()` decorators directly within the same decorator chain for a command. All grouped options must be declared using `optgroup.option()` under an `optgroup.group()`, and Click's native `click.option()` decorators should be placed outside the option group's decorator block.","error":"do not mix optgroup.option() and click.option() decorators!"},{"fix":"Always declare an option group using `@optgroup.group()` or `@optgroup()` before using `@optgroup.option()` to add options to it. For example:\n```python\nimport click\nfrom click_option_group import optgroup\n\n@click.command()\n@optgroup.group('My Group', help='A group of options')\n@optgroup.option('--foo', help='Foo option')\n@optgroup.option('--bar', help='Bar option')\ndef cli(foo, bar):\n    pass\n```","cause":"This error occurs when an `@optgroup.option()` decorator is used without an preceding `@optgroup.group()` or `@optgroup()` decorator to define the option group it belongs to. Every grouped option must be explicitly associated with a declared group.","error":"Missing declaration of the option group"},{"fix":"If you need to define positional arguments, use Click's native `@click.argument()` decorator outside of any `optgroup.group()` definition. Option groups are exclusively for `click.option`-like constructs. For example:\n```python\nimport click\nfrom click_option_group import optgroup\n\n@click.command()\n@optgroup.group('My Options')\n@optgroup.option('--name', help='A name option')\n@click.argument('files', nargs=-1)\ndef cli(name, files):\n    click.echo(f'Name: {name}, Files: {files}')\n```","cause":"The `click-option-group` library is designed to manage `options` within groups, not `arguments`. Click's `argument` decorator cannot be used directly with `optgroup` as `_Optgroup` objects do not provide an `argument` method.","error":"'_Optgroup' object has no attribute 'argument'"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.5.9","cli_name":"","install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","installed_version":"0.5.9","pypi_latest":"0.5.9","is_stale":false,"results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"click-option-group","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.05,"mem_mb":2.5,"disk_size":"18.7M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"click-option-group","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.05,"mem_mb":2.5,"disk_size":"18.6M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"click-option-group","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":1.7,"import_time_s":0.03,"mem_mb":2.5,"disk_size":"19M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"click-option-group","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.03,"mem_mb":2.5,"disk_size":"19M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"click-option-group","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.09,"mem_mb":3.1,"disk_size":"20.6M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"click-option-group","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.1,"mem_mb":3.1,"disk_size":"20.6M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"click-option-group","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":1.7,"import_time_s":0.07,"mem_mb":3.1,"disk_size":"21M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"click-option-group","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.07,"mem_mb":3.1,"disk_size":"21M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"click-option-group","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.09,"mem_mb":2.9,"disk_size":"12.5M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"click-option-group","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.07,"mem_mb":2.9,"disk_size":"12.5M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"click-option-group","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":1.5,"import_time_s":0.08,"mem_mb":2.9,"disk_size":"13M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"click-option-group","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.07,"mem_mb":2.9,"disk_size":"13M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"click-option-group","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.07,"mem_mb":3,"disk_size":"12.2M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"click-option-group","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.07,"mem_mb":3,"disk_size":"12.1M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"click-option-group","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":1.6,"import_time_s":0.07,"mem_mb":2.8,"disk_size":"13M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"click-option-group","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.07,"mem_mb":2.8,"disk_size":"13M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"click-option-group","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":null,"import_time_s":0.05,"mem_mb":2.7,"disk_size":"18.1M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"click-option-group","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.06,"mem_mb":2.7,"disk_size":"18.1M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"click-option-group","exit_code":0,"wheel_type":"wheel","failure_reason":null,"import_side_effects":"clean","install_time_s":1.9,"import_time_s":0.04,"mem_mb":2.7,"disk_size":"19M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"click-option-group","exit_code":0,"wheel_type":null,"failure_reason":null,"import_side_effects":null,"install_time_s":null,"import_time_s":0.05,"mem_mb":2.7,"disk_size":"19M"}]},"quickstart_checks":{"last_tested":"2026-04-24","tag":null,"tag_description":null,"results":[{"runtime":"python:3.10-alpine","exit_code":2},{"runtime":"python:3.10-slim","exit_code":2},{"runtime":"python:3.11-alpine","exit_code":2},{"runtime":"python:3.11-slim","exit_code":2},{"runtime":"python:3.12-alpine","exit_code":2},{"runtime":"python:3.12-slim","exit_code":2},{"runtime":"python:3.13-alpine","exit_code":2},{"runtime":"python:3.13-slim","exit_code":2},{"runtime":"python:3.9-alpine","exit_code":2},{"runtime":"python:3.9-slim","exit_code":2}]}}