click

This is the Click 8.5.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.5.0/ Changes: https://click.palletsprojects.com/page/changes/#version-8-5-0 Milestone https://github.com/pallets/click/milestone/33

• Add built-in shell completion support for PowerShell (Windows PowerShell 5.1+ and pwsh 7+) alongside the existing bash, zsh, and fish completers. Use _FOO_BAR_COMPLETE=powershell_source foo-bar to generate the completion script. #2672 #3637
• Supported versions of Windows enable ANSI terminal styles by default. Colorama is no longer a dependency and is not used. #2986 #3505
• {class}Argument accepts a help parameter, and help output includes a Positional arguments section when argument help is available. #2983 #3473
• confirm() and prompt() strip ANSI color and style codes from the prompt when the output stream does not support them, matching echo(). This stripping was lost in 8.4.0 when #2969 began writing the prompt with input() directly. #3572 #3653
• {class}Path with allow_dash=True no longer triggers a BytesWarning, an error under python -bb, when checking a value against the - convention. #2877 #3642
• Add {func}custom_version_option, a --version option whose output is produced by a callback, covering cases {func}version_option intentionally does not. The feature set of {func}version_option is now frozen; see discussion #3527. #3581
• style() and secho() no longer silently drop the 256-color index 0 (black) passed as fg or bg, and now validate color arguments. Invalid colors raise a ValueError instead of a TypeError. #3677
• The automatic help option stores its value under the reserved name _click_default_help instead of help, so a parameter named help no longer breaks parsing. The new name is visible in {meth}Command.to_info_dict output. Parameters that overwrite each other's value trigger a warning: an argument sharing its name with another parameter, or any parameter claiming the reserved name. Options may still share a name to compete for the same value (feature switches). #2819 #3678
• unstyle and the ANSI handling behind help-text wrapping now strip the full CSI escape-sequence grammar. #3681
• Streamline Option flag handling: the flag-kind, type, lazy-default and validation steps in Option.__init__ move into focused helpers, and flag_value and default keep their unset sentinel at construction (resolved lazily on read) so is UNSET reliably tells a user-supplied value from an auto-derived one. Runtime behavior is unchanged, but {meth}Parameter.to_info_dict now resolves default=True on a feature switch to its flag_value, matching what the function receives at call time. #3641
• {func}get_binary_stream and {func}get_text_stream are deprecated and will be removed in Click 9.0. #3481 #3695
• The following click.utils names were never intentionally public and are now private (_-prefixed). The old names remain available with a DeprecationWarning until Click 9.0: LazyFile, KeepOpenFile, make_default_short_help, PacifyFlushWrapper, and safecall. #3099 #3695
• Deprecate {meth}CliRunner.isolated_filesystem. It relies on {func}os.chdir, which mutates process-global state and is not thread-safe. The helper predates Python 3 and modern pytest: use a temporary directory ({class}tempfile.TemporaryDirectory or pytest's tmp_path fixture) with absolute paths instead. For running tests in parallel, use process-based isolation (such as pytest-xdist) rather than threads, since {meth}CliRunner.invoke also redirects the process-global standard streams. #3501 #3700 #3704
• prompt() is now generically typed and returns the type produced by type, value_proc, or a matching default instead of Any. {class}ParamType takes a second optional type parameter describing the input value it accepts (ParamType[int, str] for a type converting strings to integers), defaulting to Any. #3407
• {meth}Command.get_help_option_names returns the help option names in the order they were declared. #3728
• {func}get_pager_file yields a text stream on Windows again. The temporary file backend opened its file in binary mode, so writing a str to the pager raised TypeError: a bytes-like object is required, not 'str', and the color argument was ignored on that path. Regression introduced in 8.4.0 by #1572. #3731 #3732 #3740 #3739
• {func}progressbar settles on its final position when update_min_steps does not divide the total. Steps below that threshold are applied when the bar finishes, so show_pos renders 20/20 rather than the last multiple it reached. #3571 #3769
• An error raised while writing to the pager no longer gets replaced by PermissionError: [WinError 32] on Windows. The temporary file backend unlinked its file without closing it first, and Windows refuses to remove a file the process still holds open, so the cleanup failure masked the real exception. #3731 #3764
• The temporary file the pager writes to on Windows is opened with the encoding {func}get_pager_file picked for the output stream, and with errors="replace" to match the pipe backend. Any text stdout can encode reaches the pager.
• The temporary file pager backend forwards any parameters the user set in PAGER to the pager command instead of silently dropping them. On Windows, PAGER="less -R" now invokes less -R on the temporary file rather than bare less. #3777
• Improve raw mode detection by parsing the option tokens. #3416 #3777
• {func}edit accepts os.PathLike values for filename, in addition to strings. #2869 #3781

This is the Click 8.4.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.4.2/ Changes: https://click.palletsprojects.com/page/changes/#version-8-4-2 Milestone: https://github.com/pallets/click/milestone/34

• Fix Fish shell completion broken in 8.4.0 by #3126. Newlines and tabs in option help text are now escaped, keeping the original completion format while still supporting multi-line help. #3502 #3043 #3504 #3508
• Deprecated commands and options with empty or missing help text no longer render a stray leading space before the (DEPRECATED) label. #3509
• A {class}Group with invoke_without_command=True marks its subcommand as optional in the usage help, showing [COMMAND] instead of COMMAND. #3059 #3507
• echo_via_pager flushes after each write, so passing a generator streams output to the pager incrementally instead of staying hidden until the pipe buffer fills. #3242 #2542 #3534
• echo_via_pager and get_pager_file no longer close a borrowed stdout stream when no external pager runs, completing the partial I/O operation on closed file fix from #3482. #3449 #3533
• Fix CLI usage symopsis for optional arguments producing double square brackets [[a|b|c]]... whose type already brackets their metavar. #3578
• {func}version_option resolves a package_name that does not match an installed distribution as an import (top-level module) name via {func}importlib.metadata.packages_distributions. Packages whose top-level module name differs from their distribution name (PIL vs Pillow, jwt vs PyJWT) no longer raise RuntimeError out of the box. #2331 #1884 #3125 #3582

This is the Click 8.4.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.4.1/ Changes: https://click.palletsprojects.com/page/changes/#version-8-4-1 Milestone: https://github.com/pallets/click/milestone/32

• get_parameter_source() is available during eager callbacks and type conversion again. #3458 #3484
• Zsh completion scripts parse correctly on Windows. #3277 # 3466
• Shell completion of Choice Enum values produces a valid completion result. #3015
• Fix empty byte-string handling in echo. #3487
• Fix closed file error with echo_via_pager. #3449

This is the Click 8.4.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.4.0/ Changes: https://click.palletsprojects.com/page/changes/#version-8-4-0 Milestone https://github.com/pallets/click/milestone/30

• ParamType typing improvements. #3371

  • :class:ParamType is now a generic abstract base class, parameterized by its converted value type.
  • :meth:~ParamType.convert return types are narrowed on all concrete types (str for :class:STRING, int for :class:INT, etc.).
  • :meth:~ParamType.to_info_dict returns specific :class:~typing.TypedDict subclasses instead of dict[str, Any].
  • :class:CompositeParamType and the number-range base are now generic with abstract methods.

• Refactor convert_type to extract type inference into a private _guess_type helper, and add :func:typing.overload signatures. #3372

• Parameter typing improvements. #2805

  • :class:Parameter is now an abstract base class, making explicit that it cannot be instantiated directly.
  • :attr:Parameter.name is now str instead of str | None. When expose_value=False, the name is set to "" instead of None.
  • The ctx parameter of :meth:Parameter.get_error_hint is now typed as Context | None, matching the runtime behavior.

• Split string values from default_map for parameters with nargs > 1 or :class:Tuple type, matching environment variable behavior. #2745 #3364

• Auto-detect type=UNPROCESSED for flag_value of non-basic types (not str, int, float, or bool), so programmer-provided Python objects like classes and enum members are passed through unchanged instead of being stringified. Previously type=click.UNPROCESSED had to be set explicitly. #2012 #3363

• The error hint now uses Command.get_help_option_names to pick non-shadowed help option names, so Try '... -h' no longer points to a subcommand option that shadows -h. All surviving names are shown (-h/--help). #2790 #3208

• Fix readline functionality on non-Windows platforms. Prompt text is now passed directly to readline instead of being printed separately, allowing proper backspace, line editing, and line wrapping behavior. #2968 #2969

• Use :func:os.startfile on Windows to open URLs in :func:open_url, replacing the start built-in which cannot be invoked without shell=True. #3164 #3186

• Fix Fish shell completion errors when option help text contains newlines. #3043 #3126

• Add :class:NoSuchCommand exception with suggestions for misspelled commands. #3107 #3228

• Use :class:ValueError message when conversion in :class:FuncParamType would fail. #3105 #3211

• Add click.get_pager_file for file-like access to an output pager. #1572 #3405

• :class:~click.formatting.TextWrapper and :func:~click.formatting.wrap_text now measure line width in visible characters, ignoring ANSI escape sequences. #3420

• Fix :meth:HelpFormatter.write_usage emitting only a blank line when called without args. The usage prefix and program name are now written even when no arguments follow, and the trailing separator space is stripped so the line ends at the program name. #3360 #3434

• Show custom error messages from types when :func:prompt with hide_input=True fails validation, instead of always showing a generic message. Built-in type messages mask the input value. #2809 #3256

• Add capture parameter to :class:CliRunner with two modes: sys (default) and fd. fd redirects file descriptors 1 and 2 via :func:os.dup2 so output that bypasses sys.stdout (stale stream references, C extensions, subprocesses, faulthandler) is captured with proper isolation. #854 #2412 #2468 #2497 #2761 #2827 #2865

• Revert the 8.3.3 change that exposed the original file descriptor via fileno() on the redirected CliRunner streams in the default capture mode. os.dup2(w, sys.stdout.fileno()) calls inside a CLI no longer mutate the host runner's stdout, which broke Pytest's fd-level capture teardown. C-level consumers that need a real fd should use capture="fd". #3384 #3391

• Mark additional built-in strings with gettext() to extend translation coverage. #2902

• Fix feature switch groups (several flag_value options sharing one parameter name) silently dropping an explicit default when a sibling option without an explicit default was declared first. Arbitration is now source-aware: a more explicit :class:ParameterSource always wins, and within ParameterSource.DEFAULT, an option that received an explicit default= keyword wins over a sibling whose default was auto-derived. The 8.3.x first-wins fallback for remaining ties was reverted to the pre-8.3.x last-wins fallback. #3403 #3404

• Fix missing space between option help text and the (DEPRECATED) label, and localize the option label so it matches the command label. The label and the DeprecationWarning reason suffix are now produced by shared helpers. #3423

• Document short option stacking (-abc is parsed as -a -b -c) and clarify that multi-character short option names are not supported. #2779 #3431

This is the Click 8.3.3 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.3/ Changes: https://click.palletsprojects.com/page/changes/#version-8-3-3 Milestone: https://github.com/pallets/click/milestone/30

• Use :func:shlex.split to split pager and editor commands into argv lists for :class:subprocess.Popen, removing shell=True. #1026 #1477 #2775
• Fix TypeError when rendering help for an option whose default value is an object that doesn't support equality comparison with strings, such as semver.Version. #3298 #3299
• Fix pager test pollution under parallel execution by using pytest's tmp_path fixture instead of a shared temporary file path. #3238
• Treat Sentinel.UNSET values in a default_map as absent, so they fall through to the next default source instead of being used as the value. #3224 #3240
• Patch pdb.Pdb in CliRunner isolation so pdb.set_trace(), breakpoint(), and debuggers subclassing pdb.Pdb (ipdb, pdbpp) can interact with the real terminal instead of the captured I/O streams. #654 #824 #843 #951 #3235
• Add optional randomized parallel test execution using pytest-randomly and pytest-xdist to detect test pollution and race conditions. #3151
• Add contributor documentation for running stress tests, randomized parallel tests, and Flask smoke tests. #3151 #3177
• Show custom show_default string in prompts, matching the existing help text behavior. #2836 #2837 #3165 #3262 #3280 #3328
• Fix default=True with boolean flag_value always returning the flag_value instead of True. The default=True to flag_value substitution now only applies to non-boolean flags, where True acts as a sentinel meaning "activate this flag by default". For boolean flags, default=True is returned as a literal value. #3111 #3239
• Mark make_default_short_help as private API. #3189 #3250
• CliRunner's redirected streams now expose the original file descriptor via fileno(), so that faulthandler, subprocess, and other C-level consumers no longer crash with io.UnsupportedOperation. #2865
• Change :class:ParameterSource to an :class:~enum.IntEnum and reorder its members from most to least explicit, so values can be compared to check whether a parameter was explicitly provided. #2879 #3248

This is the Click 8.3.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.3.2/ Changes: https://click.palletsprojects.com/page/changes/#version-8-3-2 Milestone: https://github.com/pallets/click/milestone/29

• Fix handling of flag_value when is_flag=False to allow such options to be used without an explicit value. #3084 #3152
• Hide Sentinel.UNSET values as None when using lookup_default(). #3136 #3199 #3202 #3209 #3212 #3224
• Prevent _NamedTextIOWrapper from closing streams owned by StreamMixer. #824 #2991 #2993 #3110 #3139 #3140
• Add comprehensive tests for CliRunner stream lifecycle, covering logging interaction, multi-threaded safety, and sequential invocation isolation. Add high-iteration stress tests behind a stress marker with a dedicated CI job. #3139
• Fix callable flag_value being instantiated when used as a default via default=True. #3121 #3201 #3213 #3225

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

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

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

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

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.