# click changelog

> click release notes.

- Vendor: click
- Category: Frameworks & Libraries
- Official site: https://github.com/pallets/click
- Tracked by: What's New (https://whatsnew.fyi/product/click)
- Harvested from: GitHub (pallets/click)
- Entries below: 10 (newest first)

What's New is an index, not a publisher: every entry below links to the vendor's own release notes, which are the authoritative source. Entries are labelled where they are hand-curated sample data, pre-releases, or drawn from a secondary source such as a developer blog.

## Releases

### 8.4.2

- Date: 2026-06-26
- Version: 8.4.2
- Original notes: https://github.com/pallets/click/releases/tag/8.4.2
- Permalink: https://whatsnew.fyi/product/click/releases/8.4.2

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

### 8.4.1

- Date: 2026-05-22
- Version: 8.4.1
- Original notes: https://github.com/pallets/click/releases/tag/8.4.1
- Permalink: https://whatsnew.fyi/product/click/releases/8.4.1

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

### 8.4.0

- Date: 2026-05-17
- Version: 8.4.0
- Original notes: https://github.com/pallets/click/releases/tag/8.4.0
- Permalink: https://whatsnew.fyi/product/click/releases/8.4.0

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][version] on our website.

[version]: https://palletsprojects.com/versions

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 th

_[Truncated at 4000 characters — full notes: https://github.com/pallets/click/releases/tag/8.4.0]_

### 8.3.3

- Date: 2026-04-22
- Version: 8.3.3
- Original notes: https://github.com/pallets/click/releases/tag/8.3.3
- Permalink: https://whatsnew.fyi/product/click/releases/8.3.3

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

### 8.3.2

- Date: 2026-04-03
- Version: 8.3.2
- Original notes: https://github.com/pallets/click/releases/tag/8.3.2
- Permalink: https://whatsnew.fyi/product/click/releases/8.3.2

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

### 8.3.1

- Date: 2025-11-15
- Version: 8.3.1
- Original notes: https://github.com/pallets/click/releases/tag/8.3.1
- Permalink: https://whatsnew.fyi/product/click/releases/8.3.1

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

- Date: 2025-09-18
- Version: 8.3.0
- Original notes: https://github.com/pallets/click/releases/tag/8.3.0
- Permalink: https://whatsnew.fyi/product/click/releases/8.3.0

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][version] on our website.

[version]: https://palletsprojects.com/versions

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

- Date: 2025-08-02
- Version: 8.2.2
- Original notes: https://github.com/pallets/click/releases/tag/8.2.2
- Permalink: https://whatsnew.fyi/product/click/releases/8.2.2

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

- Date: 2025-05-20
- Version: 8.2.1
- Original notes: https://github.com/pallets/click/releases/tag/8.2.1
- Permalink: https://whatsnew.fyi/product/click/releases/8.2.1

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

- Date: 2025-05-10
- Version: 8.2.0
- Original notes: https://github.com/pallets/click/releases/tag/8.2.0
- Permalink: https://whatsnew.fyi/product/click/releases/8.2.0

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][version] on our website.

[version]: https://palletsprojects.com/versions

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`

_[Truncated at 4000 characters — full notes: https://github.com/pallets/click/releases/tag/8.2.0]_