Click

Warnings

• breaking Python 3.7, 3.8, and 3.9 support was dropped in Click 8.2.0. Projects running on those versions must pin to click<8.2.
  Fix: Upgrade Python to >=3.10 (required by current 8.3.x) or pin 'click<8.2' if stuck on older Python.
• deprecated BaseCommand and MultiCommand are deprecated since 8.2.0. Subclassing or isinstance-checking either will emit DeprecationWarnings and will break in a future major release.
  Fix: Replace BaseCommand subclasses with Command and MultiCommand subclasses/isinstance checks with Group.
• deprecated click.__version__ is deprecated since 8.2.0. Accessing it emits a DeprecationWarning.
  Fix: Use 'importlib.metadata.version("click")' for runtime version detection.
• breaking click.get_terminal_size was removed in 8.1.0. Any code importing it from click will raise ImportError. Third-party packages that imported it (e.g. older spaCy) broke on upgrade.
  Fix: Use 'shutil.get_terminal_size()' from the Python standard library instead.
• gotcha CliRunner.invoke() catches ALL exceptions by default (catch_exceptions=True), silently swallowing bugs. Tests may pass with exit_code != 0 if result.exception is not inspected.
  Fix: Pass catch_exceptions=False to CliRunner.invoke() during development, or always assert result.exception is None and result.exit_code == 0 in tests.
• gotcha CliRunner is not thread-safe and mutates global interpreter state (sys.stdout, sys.stdin). Do not use it in threaded or async test suites without isolation.
  Fix: Run CliRunner tests sequentially. Use runner.isolated_filesystem() for file-based tests to avoid cross-test contamination.
• gotcha standalone_mode=True (the default) means Click calls sys.exit() after command execution, converting return values to exit codes. Calling a click command directly in application code without standalone_mode=False will terminate the process.
  Fix: Invoke programmatically with standalone_mode=False: result = my_command.main(args=[], standalone_mode=False) to get the return value instead of a sys.exit().

Install

• pip install click pip

Imports

• click (namespace)

  import click

  All public symbols (command, group, option, argument, echo, pass_context, etc.) are accessed via the top-level 'click' namespace. Do not import from sub-modules like click.core or click.termui directly — these are private and have changed between versions.
• CliRunner

  from click.testing import CliRunner

  Testing runner lives in click.testing, not in the top-level namespace.
• Command

  from click import Command

  BaseCommand is deprecated since 8.2.0; Command is now the base class for all commands.
• Group

  from click import Group

  MultiCommand is deprecated since 8.2.0; Group is now the base class for all group commands.
• get_terminal_size

  import shutil; shutil.get_terminal_size()

  click.get_terminal_size was removed in 8.1.0. Use shutil.get_terminal_size from the stdlib.
• shell_complete (parameter)

  @click.command()
  @click.option('--name', shell_complete=my_complete_fn)

  The 'autocompletion' parameter on Command/Option was renamed to 'shell_complete' in 8.0 and the old name was fully removed.

Quickstart

A minimal Click CLI with a group, a subcommand, options, and a test via CliRunner.

import click
from click.testing import CliRunner

@click.group()
@click.option('--verbose', is_flag=True, default=False, help='Enable verbose output.')
@click.pass_context
def cli(ctx, verbose):
    """My CLI tool."""
    ctx.ensure_object(dict)
    ctx.obj['verbose'] = verbose

@cli.command()
@click.option('--count', default=1, show_default=True, help='Number of greetings.')
@click.option('--name', prompt='Your name', help='Person to greet.')
@click.pass_context
def greet(ctx, count, name):
    """Greet NAME a number of times."""
    for _ in range(count):
        click.echo(f"Hello, {name}!")
    if ctx.obj.get('verbose'):
        click.echo(f"(verbose mode, greeted {count} time(s))")

if __name__ == '__main__':
    # Direct invocation
    cli()

# --- Testing ---
def test_greet():
    runner = CliRunner()
    result = runner.invoke(cli, ['greet', '--name', 'World', '--count', '2'])
    assert result.exit_code == 0, result.output
    assert result.output.count('Hello, World!') == 2

test_greet()
click.echo('Quickstart test passed.')