Migrating to Click 8.4.0
Version 8.4.0 introduces 2 breaking changes. This guide details how to update your code.
Released: 5/17/2026
⚠️ Check Your Code
If you use any of these symbols, you need to read this guide:
ParamTypeParamType.convertParamType.to_info_dictSTRINGINTCompositeParamTypeconvert_type_guess_typeParameterParameter.nameParameter.get_error_hintContextdefault_mapTupleflag_valueclick.UNPROCESSEDCommand.get_help_option_namesopen_urlCliRunnerNoSuchCommandFuncParamTypeclick.get_pager_fileclick.formatting.TextWrapperclick.formatting.wrap_textHelpFormatter.write_usagepromptParameterSourceBreaking Changes
●Issue #1
:class:`Parameter.name` is now strictly typed as ``str`` instead of ``str | None``. When ``expose_value=False``, the name is set to ``""`` instead of ``None``.
●Issue #2
The default behavior of :class:`CliRunner` capture mode has been reverted regarding stream mutation. C-level consumers relying on the original file descriptor being exposed via ``fileno()`` on redirected streams in default capture mode must now use ``capture=\"fd\"`` to achieve that behavior.
Migration Steps
- 1If you subclassed :class:`ParamType`, ensure your implementation handles the generic typing, especially in :meth:`~ParamType.convert` return types.
- 2If you relied on ``Parameter.name`` being ``None`` when ``expose_value=False``, update code to check for ``""`` instead.
- 3Consumers of :class:`CliRunner` that need access to the original file descriptor via ``fileno()`` on redirected streams must now use ``capture=\"fd\"``.
Release Summary
Click 8.4.0 is a feature release introducing significant typing improvements across ParamType and Parameter, alongside various bug fixes related to readline, URL opening, and output capturing.
Need More Details?
View the full release notes and all changes for Click 8.4.0.
View Full Changelog