Release notes from click

8.3.2

2026-03-15T05:57:20Z

Release version 8.3.2.

8.3.1

2025-11-15T20:46:24Z

This is the Click 8.3.1 fix release, which fixes bugs but does not otherwise change behavior and should not result in breaking changes compared to the latest feature release.

PyPI: https://pypi.org/project/click/8.3.1/
Changes: https://click.palletsprojects.com/page/changes/#version-8-3-1
Milestone: https://github.com/pallets/click/milestone/28

Don't discard pager arguments by correctly using subprocess.Popen. #3039 #3055
Replace Sentinel.UNSET default values by None as they're passed through the Context.invoke() method. #3066 #3065 #3068
Fix conversion of Sentinel.UNSET happening too early, which caused incorrect behavior for multiple parameters using the same name. #3071 #3079
Fix rendering when prompt and confirm parameter prompt_suffix is empty. #3019 #3021
When Sentinel.UNSET is found during parsing, it will skip calls to type_cast_value. #3069 #3090
Hide Sentinel.UNSET values as None when looking up for other parameters through the context inside parameter callbacks. #3136 #3137

8.3.0

2025-09-18T17:34:57Z

This is the Click 8.3.0 feature release. A feature release may include new features, remove previously deprecated code, add new deprecation, or introduce potentially breaking changes.

We encourage everyone to upgrade. You can read more about our Version Support Policy on our website.

PyPI: https://pypi.org/project/click/8.3.0/
Changes: https://click.palletsprojects.com/page/changes/#version-8-3-0
Milestone https://github.com/pallets/click/milestone/27

Improved flag option handling: Reworked the relationship between flag_value
and default parameters for better consistency:
- The default parameter value is now preserved as-is and passed directly
  to CLI functions (no more unexpected transformations)
- Exception: flag options with default=True maintain backward compatibility
  by defaulting to their flag_value
- The default parameter can now be any type (bool, None, etc.)
- Fixes inconsistencies reported in: #1992 #2514 #2610
  #3024 #3030
Allow default to be set on Argument for nargs = -1. #2164
#3030
Show correct auto complete value for nargs option in combination with flag
option #2813
Show correct auto complete value for nargs option in combination with flag option #2813
Fix handling of quoted and escaped parameters in Fish autocompletion. #2995 #3013
Lazily import shutil. #3023
Properly forward exception information to resources registered with
click.core.Context.with_resource(). #2447 #3058
Fix regression related to EOF handling in CliRunner. #2939 #2940

8.2.2

2025-08-02T02:25:26Z

This is the Click 8.2.2 fix release, which fixes bugs but does not otherwise change behavior and should not result in breaking changes compared to the latest feature release.

PyPI: https://pypi.org/project/click/8.2.2/
Changes: https://click.palletsprojects.com/page/changes/#version-8-2-2
Milestone: https://github.com/pallets/click/milestone/25

Fix reconciliation of default, flag_value and type parameters for
flag options, as well as parsing and normalization of environment variables.
#2952 #2956
Fix typing issue in BadParameter and MissingParameter exceptions for the
parameter param_hint that did not allow for a sequence of string where the
underlying functino _join_param_hints allows for it. #2777 #2990
Use the value of Enum choices to render their default value in help
screen. #2911 #3004
Fix completion for the Z shell (zsh) for completion items containing
colons. #2703 #2846
Don't include envvar in error hint when not configured. #2971 #2972
Fix a rare race in click.testing.StreamMixer's finalization that manifested
as a ValueError on close in a multi-threaded test session.
#2993 #2991

8.2.1

2025-05-20T23:20:12Z

This is the Click 8.2.1 fix release, which fixes bugs but does not otherwise change behavior and should not result in breaking changes compared to the latest feature release.

PyPI: https://pypi.org/project/click/8.2.1/
Changes: https://click.palletsprojects.com/page/changes/#version-8-2-1
Milestone: https://github.com/pallets/click/milestone/24?closed=1

Fix flag value handling for flag options with a provided type. #2894 #2897
Fix shell completion for nested groups. #2906
Flush sys.stderr at the end of CliRunner.invoke. #2682
Fix EOF handling for stdin input in CliRunner. #2787

8.2.0

2025-05-18T09:48:41Z

This is the Click 8.2.0 feature release. A feature release may include new features, remove previously deprecated code, add new deprecation, or introduce potentially breaking changes.

We encourage everyone to upgrade. You can read more about our Version Support Policy on our website.

PyPI: https://pypi.org/project/click/8.2.0/
Changes: https://click.palletsprojects.com/en/stable/changes/
Milestone https://github.com/pallets/click/milestone/15

Drop support for Python 3.7, 3.8,and 3.9. #2588, #2893
Use modern packaging metadata with pyproject.toml instead of setup.cfg. #2438
Use flit_core instead of setuptools as build backend. #2543
Deprecate the __version__ attribute. Use feature detection, or importlib.metadata.version("click"), instead. #2598
BaseCommand is deprecated. Command is the base class for all commands. #2589
MultiCommand is deprecated. Group is the base class for all group commands. #2590
The current parser and related classes and methods, are deprecated.
#2205
- OptionParser and the parser module, which is a modified copy of optparse in the standard library.
- Context.protected_args is unneeded. Context.args contains any remaining arguments while parsing.
- Parameter.add_to_parser (on both Argument and Option) is unneeded. Parsing works directly without building a separate parser.
- split_arg_string is moved from parser to shell_completion.
Enable deferred evaluation of annotations with from __future__ import annotations. #2270
When generating a command's name from a decorated function's name, the suffixes _command, _cmd, _group, and _grp are removed. #2322
Show the types.ParamType.name for types.Choice options within --help message if show_choices=False is specified. #2356
Do not display default values in prompts when Option.show_default is False. #2509
Add get_help_extra method on Option to fetch the generated extra items used in get_help_record to render help text. #2516 #2517
Keep stdout and stderr streams independent in CliRunner. Always collect stderr output and never raise an exception. Add a new output stream to simulate what the user sees in its terminal. Removes the mix_stderr parameter in CliRunner. #2522 #2523
Option.show_envvar now also shows environment variable in error messages. #2695 #2696
Context.close will be called on exit. This results in all Context.call_on_close callbacks and context managers added via Context.with_resource to be closed on exit as well. #2680
Add ProgressBar(hidden: bool) to allow hiding the progressbar. #2609
A UserWarning will be shown when multiple parameters attempt to use the same name. #2396
When using Option.envvar with Option.flag_value, the flag_value will always be used instead of the value of the environment variable. #2746 #2788
Add Choice.get_invalid_choice_message method for customizing the invalid choice message. #2621 #2622
If help is shown because no_args_is_help is enabled (defaults to True for groups, False for commands), the exit code is 2 instead of 0. #1489 #1489
Contexts created during shell completion are closed properly, fixing a ResourceWarning when using click.File. #2644 #2800 #2767
click.edit(filename) now supports passing an iterable of filenames in case the editor supports editing multiple files at once. Its return type is now also typed: AnyStr if text is passed, otherwise None. #2067 #2068
Specialized typing of progressbar(length=...) as ProgressBar[int]. #2630
Improve echo_via_pager behaviour in face of errors. #2674
- Terminate the pager in case a generator passed to echo_via_pager raises an exception.
- Ensure to always close the pipe to the pager process and wait for it to terminate.
- echo_via_pager will not ignore KeyboardInterrupt anymore. This allows the user to search for future output of the generator when using less and then aborting the program using ctrl-c.
deprecated: bool | str can now be used on options and arguments. This previously was only available for Command. The message can now also be customised by using a str instead of a bool. #2263 #2271
- Command.deprecated formatting in --help changed from (Deprecated) help to help (DEPRECATED).
- Parameters cannot be required nor prompted or an error is raised.
- A warning will be printed when something deprecated is used.
Add a catch_exceptions parameter to CliRunner. If catch_exceptions is not passed to CliRunner.invoke, the value from CliRunner is used. #2817 #2818
Option.flag_value will no longer have a default value set based on Option.default if Option.is_flag is False. This results in Option.default not needing to implement __bool__. #2829
Incorrect click.edit typing has been corrected. #2804
Choice is now generic and supports any iterable value. This allows you to use enums and other non-str values. #2796 #605
Remove click.HelpOption that was introduced in 8.1.8 due to api incompatibility. #2832

Please remember, applications must lock their full dependency tree to control when updates are installed and ensure reproducible deployments. Use one of the various project management or lock tools available in the Python ecosystem. Test with warnings treated as errors to be able to adapt to deprecation warnings early.

8.1.8

2024-12-21T18:39:41Z

This is the Click 8.1.8 fix release, which fixes bugs but does not otherwise change behavior and should not result in breaking changes compared to the latest feature release.

PyPI: https://pypi.org/project/click/8.1.8/
Changes: https://click.palletsprojects.com/en/stable/changes/#version-8-1-8
Milestone https://github.com/pallets/click/milestones/23?closed=1

Fix an issue with type hints for click.open_file(). #2717
Fix issue where error message for invalid click.Path displays on
multiple lines. #2697
Fixed issue that prevented a default value of "" from being displayed in
the help for an option. #2500
The test runner handles stripping color consistently on Windows. #2705
Show correct value for flag default when using default_map. #2632
Fix click.echo(color=...) passing color to coloroma so it can be
forced on Windows. #2606.
More robust bash version check, fixing problem on Windows with git-bash. #2638
Cache the help option generated by the help_option_names setting to
respect its eagerness. #2811
Replace uses of os.system with subprocess.Popen. #1476
Exceptions generated during a command will use the context's color
setting when being displayed. #2193
Error message when defining option with invalid name is more descriptive. #2452
Refactor code generating default --help option to deduplicate code. #2563
Test CLIRunner resets patched _compat.should_strip_ansi. #2732

8.0.x

2024-10-24T20:37:08Z

last 8.0.x maintenance

7.x

2024-10-24T20:37:08Z

last 7.x maintenance

6.x

2024-10-24T20:37:08Z

last 6.x maintenance