8.5.12026-11-06
This is the Click 8.5.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.5.1/
Changes: https://click.palletsprojects.com/page/changes/#version-8-5-1
Milestone: https://github.com/pallets/click/milestone/66
- Fix copy.deepcopy() and pickle on a Parameter, Option or Command. #3805
- A KeyboardInterrupt arriving while Command.main() reports an abort or an error,
or while it exits, no longer escapes as an unhandled traceback. The command still
exits with the intended code; only the message may be lost. #3802
- Add Option.gethelpspec(), which returns the option's left help
column even when the option is hidden. Option.gethelprecord() still
returns None for hidden options, so help screens are unchanged. #3821
- The Positional arguments help section lists every argument of the command,
not only the documented ones. An argument with no help gets an empty
description, the same way an option with no help does. #3860
- Argument.gethelprecord() always returns a tuple. It used to return
None for an argument with no help. #3860
- Document which types are inferred from default, and what an unrecognized
type callable does to a command-line value. #3036 #3808
- path_type narrows the converted value's type for convert and prompt.
#3822 #3858
- Parameter accepts a new help argument, and Option and Argument
inherit it. Parameter.toinfodict() now reports help for every kind of parameter.
#3861
- A command's short help no longer stops at an abbreviation such as vs. or e.g.
inside the first sentence. A period ends the sentence only when it closes the text
or the next word does not start in lowercase. #3865
- With show_envvar=True, an option's error message now prints all variables of an
envvar sequence instead of the repr of the sequence. #3884
- An empty envvar, such as [] or "", shows the same help and error message as
no envvar when show_envvar=True. The help screen used to show [env var: ].
#3884
- Align command's deprecated help text to options and arguments: do not translate the
command's own help text, only the (DEPRECATED) label. #3901
8.5.02026-08-27
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][version] on our website.
[version]: https://palletsprojects.com/versions
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 FOOBARCOMPLETE=powershellsource 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}customversionoption, 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
clickdefault_help instead of help, so a parameter named help no
longer breaks parsing. The new name is visible in
{meth}Command.toinfodict 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.toinfodict now resolves default=True on a feature
switch to its flag_value, matching what the function receives at call
time. #3641
- {func}getbinarystream and {func}gettextstream 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,
makedefaultshort_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.gethelpoption_names returns the help option names in the
order they were declared. #3728
- {func}getpagerfile 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 updateminsteps
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}getpagerfile 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
8.4.22026-06-26
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 invokewithoutcommand=True marks its subcommand as
optional in the usage help, showing [COMMAND] instead of COMMAND.
#3059 #3507
- echoviapager 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
- echoviapager and getpagerfile 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}versionoption resolves a packagename 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.12026-05-22
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
- getparametersource() 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 echoviapager. #3449
8.4.02026-05-17
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.toinfodict 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
guesstype 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.geterrorhint 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.gethelpoption_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.getpagerfile 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
8.3.32026-04-22
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
flagvalue instead of True. The default=True to flagvalue
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 makedefaultshort_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.22026-04-03
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 `flagvalue when isflag=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.12025-11-15
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 typecastvalue. #3069 #3090
- Hide Sentinel.UNSET values as None` when looking up for other parameters through the context inside parameter callbacks. #3136 #3137
8.3.02025-09-18
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.22025-08-02
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 joinparam_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