Options¶

Adding options to commands can be accomplished with the option() decorator. At runtime the decorator invokes the Option class. Options in Click are distinct from positional arguments.

Useful and often used kwargs are:

default: Passes a default.
help: Sets help message.
nargs: Sets the number of arguments.
required: Makes option required.
type: Sets parameter type

Option Decorator ¶

The option() decorator is usually passed two positional arguments: the option name and the decorated function argument name.

@click.command()
@click.option('--string-to-echo', 'string_to_echo')
def echo(string_to_echo):
    click.echo(string_to_echo)

$ echo --help
Usage: echo [OPTIONS]

Options:
  --string-to-echo TEXT
  --help                 Show this message and exit.

However, if the decorated function argument name is not passed in, then Click will try to infer it. A simple way to name the option so that Click will infer it correctly is by taking the function argument, adding two dashes to the front and converting underscores to dashes.

@click.command()
@click.option('--string-to-echo')
def echo(string_to_echo):
    click.echo(string_to_echo)

$ echo --string-to-echo 'Hi!'
Hi!

More formally, Click will try to infer the decorated function argument name as follows:

If a positional argument is a valid Python identifier (and thus does not have dashes), it is chosen.
If multiple positional arguments are prefixed with --, the first one declared is chosen.
Otherwise, the first positional argument prefixed with - is chosen.

To get the argument name, the chosen positional argument is converted to lower case, a leading - or -- is removed if found, and any remaining - characters are replaced with _.

Examples¶
Decorator Arguments	Inferred Argument Name
`"-f", "--foo-bar"`	foo_bar
`"-x"`	x
`"-f", "--filename", "dest"`	dest
`"--CamelCase"`	camelcase
`"-f", "-fb"`	f
`"--f", "--foo-bar"`	f
`"---f"`	_f

Basic Example ¶

A simple click.Option takes one option name. By default, it’s assumed that the decorated function argument is not required and the expected type is str. If the decorated function takes a positional argument but the option is not passed with the command, then None is passed.

@click.command()
@click.option('--text')
def print_this(text):
    click.echo(text)

$ print-this --text=this
this
$ print-this

$ print-this --help
Usage: print-this [OPTIONS]

Options:
  --text TEXT
  --help       Show this message and exit.

Setting a Default ¶

Instead of setting the type, you may set a default and Click will try to infer the type.

@click.command()
@click.option('--n', default=1)
def dots(n):
    click.echo('.' * n)

$ dots --help
Usage: dots [OPTIONS]

Options:
  --n INTEGER
  --help       Show this message and exit.

Multi Value Options ¶

To make an option take multiple values, pass in nargs. Note you may pass in any positive integer, but not -1. The values are passed to the decorated function as a tuple.

@click.command()
@click.option('--pos', nargs=2, type=float)
def findme(pos):
    a, b = pos
    click.echo(f"{a} / {b}")

$ findme --pos 2.0 3.0
2.0 / 3.0

Multi Value Options as Tuples ¶

Changelog

Added in version 4.0.

By setting nargs to a specific number, each item in the resulting tuple is of the same type. Alternatively, you might want to use different types for different indexes in the tuple. For this you can directly specify a tuple as type:

@click.command()
@click.option('--item', type=(str, int))
def putitem(item):
    name, id = item
    click.echo(f"name={name} id={id}")

And on the command line:

$ putitem --item peter 1338
name=peter id=1338

By using a tuple literal as the type, nargs gets automatically set to the length of the tuple and the click.Tuple type is automatically used. The above example is thus equivalent to this:

@click.command()
@click.option('--item', nargs=2, type=click.Tuple([str, int]))
def putitem(item):
    name, id = item
    click.echo(f"name={name} id={id}")

Multiple Options ¶

The multiple options format allows options to take an arbitrary number of arguments (which is called variadic). The arguments are passed to the decorated function as a tuple. If set, default must be a list or tuple. Setting a string as default will be interpreted as a list of characters.

@click.command()
@click.option('--message', '-m', multiple=True)
def commit(message):
    click.echo(message)
    for m in message:
        click.echo(m)

$ commit -m foo -m bar -m here
('foo', 'bar', 'here')
foo
bar
here

Combining short options ¶

Short options made of a single character can be combined into one argument: -abc is equivalent to -a -b -c. This is the standard POSIX behavior for short option stacking, and it is the reason a repeated flag like -vvv works with the Counting feature.

@click.command()
@click.option('-a', is_flag=True)
@click.option('-b', is_flag=True)
@click.option('-c', is_flag=True)
def cli(a, b, c):
    click.echo(f"a={a} b={b} c={c}")

$ cli -a -b -c
a=True b=True c=True
$ cli -abc
a=True b=True c=True

If the last option in the combination takes a value, the value can either follow as the next argument or be attached directly:

@click.command()
@click.option('-v', is_flag=True)
@click.option('-n', type=int)
def cli(v, n):
    click.echo(f"v={v} n={n}")

$ cli -v -n 5
v=True n=5
$ cli -vn 5
v=True n=5
$ cli -vn5
v=True n=5

Note

Multi-character short option names are not supported. An argument like -dbg is interpreted as the combination of -d, -b, and -g, so Click reports No such option: -d if -d is not declared. For longer option names, use a long option with the -- prefix (like --debug).

Counting ¶

To count the occurrence of an option, set count=True. If the option is not passed on the command line, then the count is 0. Counting is commonly used for verbosity.

@click.command()
@click.option('-v', '--verbose', count=True)
def log(verbose):
    click.echo(f"Verbosity: {verbose}")

$ log
Verbosity: 0
$ log -vvv
Verbosity: 3

Boolean ¶

Boolean options (boolean flags) take the values True or False. The simplest case sets the default value to False if the flag is not passed, and True if it is.

import sys

@click.command()
@click.option('--shout', is_flag=True)
def info(shout):
    rv = sys.platform
    if shout:
        rv = rv.upper() + '!!!!111'
    click.echo(rv)

$ info
linux
$ info --shout
LINUX!!!!111

To implement this more explicitly, declare --{on-option}/--{off-option}. Click will automatically set is_flag=True.

import sys

@click.command()
@click.option('--shout/--no-shout', default=False)
def info(shout):
    rv = sys.platform
    if shout:
        rv = rv.upper() + '!!!!111'
    click.echo(rv)

$ info
linux
$ info --shout
LINUX!!!!111
$ info --no-shout
linux

Use cases for this more explicit pattern include:

The default can be dynamic so the user can explicitly specify the option with either on or off option, or pass in no option to use the dynamic default.
Shell scripts sometimes want to be explicit even when it’s the default
Shell aliases can set a flag, then an invocation can add a negation of the flag

If a forward slash (/) is contained in your option name already, you can split the parameters using ;. In Windows / is commonly used as the prefix character.

@click.command()
@click.option('/debug;/no-debug')
def log(debug):
    click.echo(f"debug={debug}")

Changelog

Changed in version 6.0.

If you want to define an alias for the second option only, then you will need to use leading whitespace to disambiguate the format string.

import sys

@click.command()
@click.option('--shout/--no-shout', ' /-N', default=False)
def info(shout):
    rv = sys.platform
    if shout:
        rv = rv.upper() + '!!!!111'
    click.echo(rv)

$ info --help
Usage: info [OPTIONS]

Options:
  --shout / -N, --no-shout
  --help                    Show this message and exit.

Flag Value ¶

To have a flag pass a value to the decorated function set flag_value. This automatically sets is_flag=True. To mark the flag as default, set default=True. Setting flag values can be used to create patterns like this:

import sys

@click.command()
@click.option('--upper', 'transformation', flag_value='upper', default=True)
@click.option('--lower', 'transformation', flag_value='lower')
def info(transformation):
    click.echo(getattr(sys.platform, transformation)())

$ info --help
Usage: info [OPTIONS]

Options:
  --upper
  --lower
  --help   Show this message and exit.
$ info --upper
LINUX
$ info --lower
linux
$ info
LINUX

How `default` and `flag_value` interact ¶

The default value is given to the underlying function as-is. So if you set default=None, the function receives None. Same for any other type.

But there is a special case for non-boolean flags: if a flag has a non-boolean flag_value (like a string or a class), then default=True is interpreted as the flag should be activated by default. The function receives the flag_value, not the Python True.

Which means, in the example above, this option:

@click.option('--upper', 'transformation', flag_value='upper', default=True)

is equivalent to:

@click.option('--upper', 'transformation', flag_value='upper', default='upper')

Because the two are equivalent, it is recommended to always use the second form and set default to the actual value you want. This makes code more explicit and predictable.

This special case does not apply to boolean flags (where flag_value is True or False). For boolean flags, default=True is the literal Python value True.

The tables below show the value received by the function for each combination of default, flag_value, and whether the flag was passed on the command line.

Boolean flags (`is_flag=True`, boolean `flag_value`)¶

These are flags where flag_value is True or False. The default value is always passed through literally without any special substitution.

`default`	`flag_value`	Not passed	`--flag` passed
(unset)	(unset)	`False`	`True`
`True`	(unset)	`True`	`True`
`False`	(unset)	`False`	`True`
`None`	(unset)	`None`	`True`
`True`	`True`	`True`	`True`
`True`	`False`	`True`	`False`
`False`	`True`	`False`	`True`
`False`	`False`	`False`	`False`
`None`	`True`	`None`	`True`
`None`	`False`	`None`	`False`

Tip

For a negative flag that defaults to off, prefer the explicit pair form --with-xyz/--without-xyz over the single-flag flag_value=False, default=True:

@click.option('--with-xyz/--without-xyz', 'enable_xyz', default=True)

Boolean flag pairs (`--flag/--no-flag`)¶

These use secondary option names to provide both an on and off switch. The default value is always literal.

`default`	Not passed	`--flag`	`--no-flag`
(unset)	`False`	`True`	`False`
`True`	`True`	`True`	`False`
`False`	`False`	`True`	`False`
`None`	`None`	`True`	`False`

Non-boolean feature switches (`flag_value` is a string, class, etc.)¶

For these flags, default=True is a special case: it means “activate this flag by default” and resolves to the flag_value. All other default values are passed through literally.

`default`	`flag_value`	Not passed	`--flag` passed
(unset)	`"upper"`	`None`	`"upper"`
`True`	`"upper"`	`"upper"`¹	`"upper"`
`"lower"`	`"upper"`	`"lower"`	`"upper"`
`None`	`"upper"`	`None`	`"upper"`

Hint

¹: default=True is substituted with flag_value.

Feature switch groups (multiple flags sharing one variable)¶

Several flag_value options can target the same parameter name to form a feature switch group. The user picks one flag on the command line, and the function receives the corresponding flag_value. When the user picks none, Click falls back to whichever option claims the slot under the arbitration rules described below.

Non-boolean groups¶

For non-boolean flag_value (strings, enum members, classes, …), place default=True on the option that should win when no flag is passed. The substitution rule above resolves it to that option’s flag_value. Any other explicit default is passed through literally.

Definition	Not passed	`--upper`	`--lower`
`--upper` with `flag_value='upper'`, `default=True`	`"upper"`	`"upper"`	`"lower"`
`--upper` with `flag_value='upper'`, `default='upper'`	`"upper"`	`"upper"`	`"lower"`
`--upper` with `flag_value='upper'`, `default=None`	`None`	`"upper"`	`"lower"`
Neither option carries a `default`	`None`	`"upper"`	`"lower"`

The third row is the three-state pattern: the function receives None when no flag is passed, distinguishable from either explicit choice.

Boolean groups¶

When flag_value is True or False, the substitution rule does not apply: default=True is the literal Python True. To make one flag in an enable/disable pair the default, set its default=True explicitly:

@click.option("--without-xyz", "enable_xyz", flag_value=False)
@click.option("--with-xyz", "enable_xyz", flag_value=True, default=True)

Definition	Not passed	`--with-xyz`	`--without-xyz`
`--with-xyz` with `flag_value=True`, `default=True`	`True`	`True`	`False`
`--without-xyz` with `flag_value=False`, `default=False`	`False`	`True`	`False`
`--with-xyz` with `flag_value=True`, `default=None`	`None`	`True`	`False`
Neither option carries a `default`	`False`	`True`	`False`

Tip

For most enable/disable cases, the pair form --with-xyz/--without-xyz is shorter and equivalent. The multi-flag group form is useful when the on and off flags need distinct names without a shared stem, or when each flag needs its own help text.

Arbitration rules¶

When several options in a group resolve their values simultaneously, only one wins the parameter slot. The full arbitration policy (source precedence, explicit-beats-auto tie-break, last-declared fallback) is enumerated under Option value resolution.

Option value resolution ¶

This section enumerates the rules Click applies when computing the value delivered to the decorated function for every option. Rules are listed in the order they fire during the parsing pipeline.

Type inference ¶

Without an explicit type=, Click infers the parameter type at construction:

If flag_value is True or False, the type is BoolParamType.
If flag_value is an int, float, or str, the type is the matching basic type.
If flag_value is any other Python object (a class, an enum member, a frozenset, …), the type is UNPROCESSED so the value passes through unchanged.
Otherwise, the type is inferred from default if set, falling back to StringParamType when neither hint is available.

`default` interpretation ¶

The literal value passed as default= is interpreted differently depending on whether the option is a flag and what flag_value it carries:

default=UNSET (the absence sentinel) is treated as if default was not passed at all. It does not count as “the user picked nothing”, and it does not count as an explicit default for arbitration purposes.
For a bare boolean flag (no flag_value, or flag_value of True or False), an unset default auto-derives to False.
For a non-boolean flag with a flag_value, default=True is substituted with flag_value. This is the “activate this flag by default” shorthand. Any non-True default is passed through literally.
For a boolean flag with flag_value set, default=True is the literal Python True. The substitution from rule 3 does not apply.
default=None is always a real explicit value, distinct from UNSET absence.
Any other default is delivered to the function unchanged after conversion through the parameter’s type.

Value sources ¶

Click resolves the value of every option from the following sources, in order of decreasing precedence:

command line input (ParameterSource.COMMANDLINE),
environment variable named in envvar= or derived from auto_envvar_prefix (ParameterSource.ENVIRONMENT),
default_map entry matching the parameter name on the active Context (ParameterSource.DEFAULT_MAP),
parameter default (ParameterSource.DEFAULT).

The first source that produces a value wins. Environment variables and default_map entries set to Sentinel.UNSET are skipped, so they fall through to the next source rather than supplying UNSET to the function.

If after the four sources above no explicit value was found (or only a default_map/default value was) and the option declares prompt=, Click prompts the user for one. The resulting value is recorded as ParameterSource.PROMPT, which ranks above every source listed above for arbitration purposes (see Slot arbitration).

Slot arbitration ¶

Several options can target the same name to form a feature switch group. When they do, only one option’s value reaches the function. Arbitration applies these rules, in order:

By source. Whichever option resolved its value from the most explicit source wins, regardless of decorator order. Any command-line input beats any default, an environment variable beats a default_map entry, and so on.
Within the default tier, explicit beats auto-derived. An option that received an explicit default= keyword wins over one whose default came from default interpretation.
Otherwise, last declared wins. When all options in the group resolved from the same source and tier (all auto-derived defaults, or all explicit defaults), the option declared last in the source code keeps the slot.

Values from Environment Variables ¶

To pass in a value from a specific environment variable use envvar.

@click.command()
@click.option('--username', envvar='USERNAME')
def greet(username):
   click.echo(f"Hello {username}!")

$ export USERNAME=john
$ greet
Hello john!

If a list is passed to envvar, the first environment variable found is picked.

@click.command()
@click.option('--username', envvar=['ALT_USERNAME', 'USERNAME'])
def greet(username):
   click.echo(f"Hello {username}!")

$ export ALT_USERNAME=Bill
$ export USERNAME=john
$ greet
Hello Bill!

Variable names are:

Case-insensitive on Windows but not on other platforms.
Not stripped of whitespace and should match the exact name provided to the envvar argument.

For flag options, there are two concepts to consider: the activation of the flag driven by the environment variable, and the value of the flag if it is activated.

The values read from environment variables are always strings and will require extra processing. We need to transform these strings into boolean values that will determine if the flag is activated or not.

Here are the rules used to parse environment variable values for flag options:

true, 1, yes, on, t, y are interpreted as activating the flag
false, 0, no, off, f, n are interpreted as deactivating the flag
The presence of the environment variable without value is interpreted as deactivating the flag
Empty strings are interpreted as deactivating the flag
Values are case-insensitive, so the True, TRUE, tRuE strings are all interpreted as activating the flag
Values are stripped of leading and trailing whitespace before being interpreted, so the " True " string is transformed to "true" and thus activates the flag
If the flag option has a flag_value argument, passing that value in the environment variable will activate the flag, in addition to all the cases described above
Any other value is interpreted as deactivating the flag

Caution

For boolean flags with a pair of values, the only recognized environment variable is the one provided to the envvar argument.

So an option defined as --flag/--no-flag, with an envvar="FLAG" parameter, there is no magical NO_FLAG=<anything> variable that is recognized. Only the FLAG=<anything> environment variable is recognized.

If the flag is activated, its value is set to flag_value. Otherwise, the value defaults to None.

Multiple Options from Environment Values ¶

As options can accept multiple values, pulling in such values from environment variables (which are strings) is a bit more complex. Click handles this by deferring customization of the behavior to the type. For both multiple and nargs with values other than 1, Click will invoke the ParamType.split_envvar_value() method to perform the splitting.

The default implementation for all types is to split on whitespace. The exceptions to this rule are the File and Path types which both split according to the operating system’s path splitting rules. On Unix systems like Linux and OS X, the splitting happens on every colon (:), and for Windows, splitting on every semicolon (;).

@click.command()
@click.option('paths', '--path', envvar='PATHS', multiple=True,
              type=click.Path())
def perform(paths):
    for path in paths:
        click.echo(path)

if __name__ == '__main__':
    perform()

$ export PATHS=./foo/bar:./test
$ perform
./foo/bar
./test

Other Prefix Characters ¶

Click can deal with prefix characters besides - for options, including / and +, as well as others. Note that alternative prefix characters are generally used very sparingly if at all within POSIX.

@click.command()
@click.option('+w/-w')
def chmod(w):
    click.echo(f"writable={w}")

$ chmod +w
writable=True
$ chmod -w
writable=False

There are special considerations for using / as prefix character. See Boolean for more.

Optional Value ¶

Providing the value to an option can be made optional, in which case providing only the option’s flag without a value will either show a prompt or use its flag_value.

Setting is_flag=False, flag_value=value tells Click that the option can still be passed a value, but if only the flag is given, the value will be flag_value.

@click.command()
@click.option("--name", is_flag=False, flag_value="Flag", default="Default")
def hello(name):
    click.echo(f"Hello, {name}!")

$ hello
Hello, Default!
$ hello --name Value
Hello, Value!
$ hello --name
Hello, Flag!

Options¶

Option Decorator ¶

Basic Example ¶

Setting a Default ¶

Multi Value Options ¶

Multi Value Options as Tuples ¶

Multiple Options ¶

Combining short options ¶

Counting ¶

Boolean ¶

Flag Value ¶

How `default` and `flag_value` interact ¶

Boolean flags (`is_flag=True`, boolean `flag_value`)¶

Boolean flag pairs (`--flag/--no-flag`)¶

Non-boolean feature switches (`flag_value` is a string, class, etc.)¶

Option value resolution ¶

Type inference ¶

`default` interpretation ¶

Value sources ¶

Slot arbitration ¶

Values from Environment Variables ¶

Multiple Options from Environment Values ¶

Other Prefix Characters ¶

Optional Value ¶

Contents

Navigation

Options¶

Boolean flags (is_flag=True, boolean flag_value)¶

Boolean flag pairs (--flag/--no-flag)¶

Non-boolean feature switches (flag_value is a string, class, etc.)¶

Feature switch groups (multiple flags sharing one variable)¶

Non-boolean groups¶

Boolean groups¶

Arbitration rules¶

Boolean flags (`is_flag=True`, boolean `flag_value`)¶

Boolean flag pairs (`--flag/--no-flag`)¶

Non-boolean feature switches (`flag_value` is a string, class, etc.)¶