click-aliases

library1.0.7pypypi✓ verified 25d ago

click-aliases is a Python library that extends Click, a popular CLI creation kit, by allowing developers to assign multiple distinct aliases to commands and groups. It addresses Click's lack of built-in 'true' command aliasing (beyond prefix matching) by providing a custom group class. The current version is 1.0.5, released in October 2024, and it generally follows a maintenance release cadence.

devops

pip install click-aliases

package ↗

INSTALL

IMPORT

SIG · CLICK-ALIASES

click-aliases

devopspythonv1.0.7

Install

1.7s avg

Import

133ms

Disk

17MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.0.7 · 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.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.140s · 18.7MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.7s · import 0.126s · 19MB

17MB installed

● package 17MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

ClickAliasedGroup

✓ from click_aliases import ClickAliasedGroup

This is the primary class to import and use with @click.group(cls=ClickAliasedGroup).

This example demonstrates how to set up a Click CLI with `click-aliases`. The `ClickAliasedGroup` is passed as the class for the main Click group, and then individual commands can specify aliases using the `aliases` argument in the `@cli.command()` decorator.

import click from click_aliases import ClickAliasedGroup @click.group(cls=ClickAliasedGroup) def cli(): """A simple CLI with aliases.""" pass @cli.command(aliases=['create', 'mk']) def make(): """Makes something new.""" click.echo('Making something...') @cli.command(aliases=['rm', 'delete']) def remove(): """Removes something.""" click.echo('Removing something...') if __name__ == '__main__': cli()

Debug

Known issues

gotchaClick's native functionality supports command prefix matching (e.g., 'comm' for 'commit' if unique), but not 'true' distinct aliases. `click-aliases` provides the latter. Be aware of this distinction to avoid confusion about which form of aliasing you need.

fix

Understand that `click-aliases` is for defining explicit, distinct alternative names for commands, not for automatically shortening command names (which Click handles to a degree).

affects: All versions

gotchaWhen combining `click-aliases` with other Click extensions (e.g., `rich-click`), there might be conflicts or unexpected behavior, particularly regarding help text formatting. Aliases may not appear correctly or may break the formatting of individual command help.

fix

Test thoroughly when using multiple Click extensions. For help output issues, custom `HelpFormatter` implementations or further overrides of Click's core classes might be required to integrate alias display seamlessly.

affects: All versions

deprecatedClick's core maintainers have previously indicated that alias functionality is covered by overridable APIs and is not planned for direct integration into Click's core. While `click-aliases` provides a convenient abstraction, users should be aware that native support for this specific aliasing pattern is unlikely to be added to Click itself.

fix

Continue using `click-aliases` or implement custom group classes as shown in Click's advanced patterns if more fine-grained control is needed. This warning is more about Click's design philosophy than a deprecation within `click-aliases`.

affects: All versions of Click and click-aliases

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'click_aliases'

The 'click-aliases' library has not been installed in the current Python environment.

fix

pip install click-aliases

ModuleNotFoundError: No module named 'click'

The foundational 'click' library, which 'click-aliases' depends on, is not installed in the current Python environment.

fix

pip install click

TypeError: __init__() got an unexpected keyword argument 'aliases'

You are attempting to use the 'aliases' keyword in a Click group or command decorator without properly applying 'click-aliases''s 'ClickAliasedGroup' class, or an older version of 'rich-click' is in use which doesn't support the 'aliases' parameter.

fix

Ensure your `@click.group` decorator specifies `cls=ClickAliasedGroup` and that you import `ClickAliasedGroup` from `click_aliases`. If using `rich-click`, ensure it's version 1.9.0 or newer, or correctly compose `ClickAliasedGroup` with `rich_click.RichGroup`.

```python
from click_aliases import ClickAliasedGroup
import click

@click.group(cls=ClickAliasedGroup)
def cli():
    pass

@cli.command(aliases=['my-alias', 'ma'])
def my_command():
    click.echo("Hello from my_command!")
```

Command alias not working

This usually indicates that the 'ClickAliasedGroup' class is not correctly applied to the main `click.group`, or the aliases are not passed as expected to the command decorator, preventing Click from recognizing or displaying them.

fix

Verify that `ClickAliasedGroup` is imported and passed as the `cls` argument to your top-level `click.group` decorator, and that aliases are provided as a list to the `aliases` keyword argument in your `@command` decorator.

```python
from click_aliases import ClickAliasedGroup
import click

@click.group(cls=ClickAliasedGroup)
def cli():
    """A CLI with aliases."""
    pass

@cli.command(aliases=['hello-alias', 'h-a'])
def hello():
    """Says hello."""
    click.echo("Hello!")

if __name__ == '__main__':
    cli()
```

Upgrade

Version history

1.0.7latest on PyPI · released Jul 9, 2026

Audit

Dependencies

clickrequiredclick-aliases is an extension for the Click framework, requiring it for core functionality.

Agent activity

11 hits · last 30 days

node

Resources

packagehttps://pypi.org/project/click-aliases/ ↗