click-extra

7.14.1 verified Fri May 01 auth: no python

A drop-in replacement for Click that adds colorful and user-friendly CLI output, extended help formatting, table rendering, configuration management, and more. Version 7.14.1 supports Python >=3.10 and acts as a thin wrapper around Click, providing extra decorators, commands, and utilities. Releases are frequent, typically monthly.

pip install click-extra

Common errors

error ImportError: cannot import name 'ExtraGroup' from 'click_extra' ↓

cause Installed version is too old (pre-7.0) or package not installed correctly.

fix

Upgrade to latest: pip install --upgrade click-extra; verify import with from click_extra import ExtraGroup.

error TypeError: ExtraGroup.__init__() got an unexpected keyword argument 'version' ↓

cause Using `version=` parameter which was removed in version 7.7.0.

fix

Replace version='x.y.z' with version_fields={'version': 'x.y.z'} or remove it if using auto-detection.

error click_extra.wrap: error: SCRIPT must be a console_scripts entry point or module:function ↓

cause The `wrap` command requires a proper entry point; bare script names like `my-script.py` won't work.

fix

Use an installed package name (e.g., pip install mypackage) and then click-extra wrap mypackage.

Warnings

breaking In version 7.7.0, the `version` parameter was removed from `ExtraCommand` and `ExtraGroup`. Use `version_fields` instead. ↓

fix Replace `version=value` with `version_fields={'version': value}` or use `ExtraVersionOption` directly.

deprecated The `config_schema` parameter accepts both dataclasses and callables. Legacy config section names using `fallback_sections` will issue deprecation warnings in future versions. ↓

fix Migrate your config section names to the new default and remove `fallback_sections`.

gotcha When using `click-extra`'s `wrap` subcommand, the target script must be a valid console_scripts entry point or a `module:function` string. Otherwise, it will fail silently or produce no output. ↓

fix Ensure the SCRIPT argument matches an installed entry point (e.g., from pyproject.toml) or is in `module:function` format.

gotcha The `click-extra` `ExtraGroup` changes Click's default help ordering and adds color by default. Existing Click code that relies on default help behavior may see different formatting. ↓

fix If you need standard Click behavior, use `cls=click.Group` instead of `ExtraGroup`, or pass `colorize=False` to the decorator.

Imports

ExtraGroup
wrong
```
from click_extra.commands import ExtraGroup
```
correct
```
from click_extra import ExtraGroup
```
ExtraGroup is re-exported from the top-level package; importing from click_extra.commands may break if internal structure changes.
ExtraCommand
```
from click_extra import ExtraCommand
```
Direct top-level import is the stable API.
help_option
wrong
```
from click import help_option
```
correct
```
from click_extra import help_option
```
click-extra overrides the Click help option; using Click's original will miss colorization.
version_option
wrong
```
from click.decorators import version_option
```
correct
```
from click_extra import version_option
```
click-extra's version_option supports extra fields like git_branch.

config_option

wrong

from click_extra.decorators import config_option

correct

from click_extra import config_option

Top-level export is the intended public API.

Quickstart

Creates a CLI with colorful help using ExtraGroup and the click-extra help option.

import click
from click_extra import ExtraGroup, help_option

@click.group(cls=ExtraGroup)
@click.option('--name', default='world', help='Who to greet.')
@click.pass_context
def cli(ctx, name):
    ctx.ensure_object(dict)
    ctx.obj['name'] = name

@cli.command()
@help_option('-h', '--help')
@click.pass_context
def greet(ctx):
    click.echo(f"Hello, {ctx.obj['name']}!")

if __name__ == '__main__':
    cli()