●Change8

Migrating to Click 8.2.0

Version 8.2.0 introduces 8 breaking changes. This guide details how to update your code.

Released: 5/10/2025

8
Breaking Changes
9
Migration Steps
21
Affected Symbols

⚠️ Check Your Code

If you use any of these symbols, you need to read this guide:

__version__BaseCommandMultiCommandOptionParserparserContext.protected_argsParameter.add_to_parsersplit_arg_stringOption.show_defaultOption.show_envvarContext.closeProgressBarChoiceclick.editecho_via_pagerOption.deprecatedCommand.deprecatedCliRunnerCliRunner.mix_stderrclick.HelpOptionOption.flag_value

Breaking Changes

●Issue #1

Dropped support for Python 3.7, 3.8, and 3.9. Projects must run on Python >=3.10.

●Issue #2

Removed `click.HelpOption` API; importing it will raise ImportError. Use the built‑in help handling instead.

●Issue #3

Removed the `mix_stderr` parameter from `CliRunner`; code that passes this argument will raise a TypeError and must be updated to rely on the independent stdout/stderr streams.

●Issue #4

Removed the `parser` module and `OptionParser` class; any imports from `click.parser` will break. Switch to Click's built‑in parsing (no external parser needed).

●Issue #5

Removed `Context.protected_args`; use `Context.args` for remaining arguments.

●Issue #6

Removed `Parameter.add_to_parser`; custom parser hooks must be refactored to use Click's automatic parsing.

●Issue #7

`Option.flag_value` no longer defaults based on `Option.default` when `is_flag` is false; code that relied on that implicit default must set `flag_value` explicitly.

●Issue #8

When `no_args_is_help` triggers help, the exit code is now 2 instead of 0; scripts or tests expecting exit code 0 need to be adjusted.

Migration Steps

  1. 1
    Replace any usage of `click.__version__` with `importlib.metadata.version("click")`.
  2. 2
    Swap `BaseCommand` subclasses for `Command` and `MultiCommand` subclasses for `Group`.
  3. 3
    Remove imports of `click.parser`, `OptionParser`, and any references to `Context.protected_args` or `Parameter.add_to_parser`; use the new APIs instead.
  4. 4
    If you passed `mix_stderr` to `CliRunner`, delete that argument and rely on the independent stdout/stderr streams.
  5. 5
    Update code that relied on `Option.flag_value` defaulting from `Option.default` when `is_flag` is false by explicitly setting `flag_value` where needed.
  6. 6
    Adjust test expectations for help output triggered by `no_args_is_help` to expect exit code 2.
  7. 7
    If you used `click.HelpOption`, remove it and rely on Click's built‑in `--help` handling.
  8. 8
    Review any custom deprecation messages; you can now pass a string to `deprecated` on options/arguments.
  9. 9
    If you used `click.edit` with a single filename, you can now also pass an iterable of filenames; update type hints accordingly.

Release Summary

Click 8.2.0 introduces numerous new features, deprecates legacy APIs, drops Python 3.7‑3.9 support, and removes several breaking symbols such as `click.HelpOption` and `mix_stderr`.

Need More Details?

View the full release notes and all changes for Click 8.2.0.

View Full Changelog