cloup

library3.1.0pypypi✓ verified 24d ago

Cloup — originally from 'Click + option groups' — enriches the popular Click library with several features that make command-line interfaces more expressive and configurable. These include option groups, constraints (e.g., mutually exclusive parameters), subcommand aliases, subcommand sections, and a themeable help formatter. The library, currently at version 3.0.9, is under active development, statically type-checked with MyPy, and extensively tested.

web-framework

pip install cloup

github ↗package ↗

INSTALL

IMPORT

SIG · CLOUP

cloup

web-frameworkpythonv3.1.0

Install

1.7s avg

Import

176ms

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 v3.1.0 · 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.184s · 19.4MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.7s · import 0.168s · 20MB

17MB installed

● package 17MB

Code

Verified usage

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

command

✓ from cloup import command

option

✓ from cloup import option

option_group

✓ from cloup import option_group

HelpFormatter

✓ from cloup import HelpFormatter

HelpTheme

✓ from cloup import HelpTheme

Style

✓ from cloup import Style

RequireAtLeast

✓ from cloup.constraints import RequireAtLeast

mutually_exclusive

✓ from cloup.constraints import mutually_exclusive

This quickstart demonstrates how to define a command with custom help formatting, option groups, and constraints. It uses `option_group` to logically group related options and applies `mutually_exclusive` and `RequireAtLeast` constraints.

import cloup from cloup import command, option, option_group, HelpFormatter, HelpTheme, Style from cloup.constraints import RequireAtLeast, mutually_exclusive # Configure a custom help theme for better readability formatter_settings = HelpFormatter.settings( theme=HelpTheme( invoked_command=Style(fg='bright_yellow'), heading=Style(fg='bright_white', bold=True), constraint=Style(fg='magenta'), col1=Style(fg='bright_yellow'), ) ) @command(formatter_settings=formatter_settings) @option_group( "Cool options", option('--foo', help='This text describes the option --foo.'), option('--bar', help='This text describes the option --bar.'), constraint=mutually_exclusive, ) @option_group( "Other cool options", "This is an optional description for this option group.", option('--pippo', help='This text describes the option --pippo.'), option('--pluto', help='This text describes the option --pluto.'), constraint=RequireAtLeast(1), ) @option('--verbose', '-v', is_flag=True, help='Enable verbose output.') def cli(foo, bar, pippo, pluto, verbose): """A simple CLI demonstrating Cloup's features.""" if verbose: cloup.echo('Verbose mode enabled.') cloup.echo(f'Foo: {foo}, Bar: {bar}, Pippo: {pippo}, Pluto: {pluto}') if __name__ == '__main__': cli(prog_name='my-app')

Debug

Known issues

breakingIn Cloup v3.0.0, `HelpTheme` was changed from a `NamedTuple` to a `dataclass`. While the change was noted as unlikely to affect most users, it is a structural modification that could impact direct instantiation or introspection of `HelpTheme` objects.

fix

Review any code directly interacting with `HelpTheme`'s internal structure or inheritance. Adapt to `dataclass` behavior if necessary.

affects: >=3.0.0

breakingCloup v3.0.6 dropped support for Python 3.7. Users on Python 3.7 must use an older version of Cloup.

fix

Upgrade Python to 3.8 or newer, or pin Cloup to a version `<=3.0.5`.

affects: >=3.0.6

gotchaCloup v3.0.3 redefined `click.pass_context` and `click.get_current_context` to internally use `cloup.Context` instead of `click.Context`. Directly mixing explicit `click.Context` usage with `cloup.Context` in earlier versions could lead to unexpected behavior.

fix

Ensure consistent use of `cloup.Context` where Cloup features are utilized, or upgrade to `cloup>=3.0.3` which aims to improve compatibility.

affects: <3.0.3

gotchaPrior to v3.0.9, Cloup might have triggered a `click.__version__` deprecation warning due to changes in how Click's version was accessed. This was fixed in v3.0.9.

fix

Upgrade to Cloup v3.0.9 or newer to resolve the `click.__version__` deprecation warning.

affects: <3.0.9

gotchaIn versions prior to 3.0.7, constraints might not have worked correctly with options that had more than two names (e.g., `--one -o --option-one`). This bug was fixed in v3.0.7.

fix

Upgrade to Cloup v3.0.7 or newer to ensure constraints function correctly with all option name configurations.

affects: <3.0.7

gotchaCloup's `Group` class (e.g., used with `@cloup.group`) does not natively support option groups or constraints by default, unlike `cloup.Command`. This is an intentional design choice for simpler groups.

fix

If option groups or constraints are needed for a `cloup.Group`, consider using `cloup.Command` for the top-level CLI or explicitly subclass `cloup.Group` and add the necessary mixins (e.g., `OptionGroupMixin`, `ConstraintMixin`) as described in Cloup's advanced documentation.

affects: All versions

Errors

Common errors & fixes

Error: at least 1 of the following parameters must be set: --option1 --option2

This error occurs when a Cloup option group or set of parameters has a constraint, such as `RequireAtLeast(1)` or `mutually_exclusive`, that is not satisfied by the provided command-line arguments.

fix

Ensure that the required number of options within the constrained group are provided when invoking the command. For example, if `--option1` or `--option2` is required, provide one of them: `your_command --option1 value`.

ModuleNotFoundError: No module named 'cloup'

This error indicates that the 'cloup' package is not installed in the Python environment being used, or the Python interpreter cannot find it in its search path.

fix

Install the cloup library using pip: `pip install cloup` or activate the correct Python environment where cloup is installed.

TypeError: argument of type 'HelpFormatter' is not iterable

This TypeError can arise if you are mixing Click's default `HelpFormatter` with Cloup's `OptionGroupMixin` or other Cloup features that expect `cloup.HelpFormatter`. This typically happens when a Click `HelpFormatter` is passed where a `cloup.HelpFormatter` is implicitly or explicitly required.

fix

Ensure you are consistently using `cloup.HelpFormatter` when working with Cloup's advanced formatting features. You can define `formatter_class=cloup.HelpFormatter` in your command's `context_settings` or use `cloup.Command` which uses it by default.

AttributeError: 'Group' object has no attribute 'section'

This error occurs when attempting to use Cloup's subcommand sectioning features (e.g., `group.section()`) on a standard `click.Group` instance, instead of a `cloup.Group` instance or a custom group class that inherits from `cloup.SectionMixin`.

fix

To use subcommand sections, ensure your group is created using `@cloup.group` (which returns a `cloup.Group` by default) or explicitly make your group class inherit from `cloup.Group` or `cloup.SectionMixin`.

Upgrade

Version history

3.1.0latest on PyPI · released May 26, 2026

Audit

Dependencies

clickrequiredCloup is an extension of Click and builds upon its core functionalities.

Agent activity

10 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/janLuke/cloup ↗

packagehttps://pypi.org/project/cloup/ ↗