---
id: cloup
version: "3.1.0"
license: BSD 3-Clause
license_treatment: permissive
maintenance: active
---

# cloup — Adds features to Click: option groups, constraints, subcommand sections and help themes.

License: permissive · Maintenance: active · Downloads: 1.1M/mo

## What it is and what it does

Cloup is a Click extension that adds structured organization and validation to command-line interfaces. It lets you group related options, apply constraints like mutual exclusivity or minimum-required counts, organize subcommands into sections, and customize help output with themes and colors. The package is built on top of Click and adds decorators with detailed type hints, making it easier to write complex CLIs with better IDE support and validation.

The library is actively maintained, supports Python 3.9 through 3.13, and has no known security vulnerabilities. It depends only on Click and typing_extensions, keeping installation lightweight. The codebase is statically type-checked with MyPy and extensively tested, making it suitable for production CLI applications where you need more control over option organization and user-facing validation messages.

Use it for:

- Organize related CLI options into labeled groups with shared constraints like mutual exclusivity or minimum-required selections
- Build multi-level command hierarchies with subcommands organized into logical sections in the help output
- Apply conditional parameter validation (e.g., require at least N of a group, or enforce mutual exclusivity) without manual checking
- Customize help text appearance with themed colors and styles, including responsive layouts for narrow terminals
- Provide "did you mean?" suggestions when users mistype subcommand names

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Cloup extends Click with option groups, parameter constraints, subcommand sections, themeable help formatting, and subcommand aliases to build more expressive command-line interfaces.

Yes. Cloup is a lightweight, actively maintained extension that solves real CLI organization and validation problems. If you're building a Click-based CLI with multiple options or subcommands, Cloup's option groups and constraints eliminate boilerplate validation code and improve help readability. The permissive license, low dependency footprint, and current Python version support make it a safe, practical choice.

## Install

pip install cloup
uv add cloup
poetry add cloup

## Installing cloup

Before you install: Low install friction with only two runtime dependencies (click and typing_extensions). Actively maintained with a release 80 days ago and recent commits; supports Python 3.9 through 3.13.

License in practice: BSD 3-Clause is permissive; you can use, modify, and distribute this package with minimal restrictions, provided you include the license notice.

Quickstart:

pip install cloup

from cloup import command, option_group, option
from cloup.constraints import mutually_exclusive

@command()
@option_group(
    "Options",
    option('--foo'),
    option('--bar'),
    constraint=mutually_exclusive,
)
def cmd(**kwargs):
    pass

if __name__ == '__main__':
    cmd()

Verify before relying:

- Whether the 100% test coverage claim and MyPy strict-mode checking are maintained in the current release
- Performance impact of constraint validation on large option sets or deeply nested command hierarchies

## Package facts

- License: BSD 3-Clause (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 1.1M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

click option groups, cli parameter constraints, command-line help themes, subcommand organization, mutually exclusive options, click extensions, terminal ui styling, cli-framework, click-extension

[View on SkillFed](https://skillfed.io/packages/cloup) · [View on PyPI](https://pypi.org/project/cloup/)