Skip to content

Upgrading clap 3 to 4

Breaking3.2.25 → 4.6.7Breaking26Platform3Deprecated6New71Changed66Fixed156Other46

BreakingUpgrade verdict

26 breaking changes and 3 platform requirement changes.

  • name/version header was removed because we couldn't justify the space it occupied when.
  • ArgAction::Set, ArgAction::SetTrue, and Arg::Action::SetFalse now conflict by default to be like ArgAction::StoreValue and ArgAction::IncOccurrences, requiring cmd.args_override_self(true) to…
  • By default, an Args default action is ArgAction::Set, rather than ArgAction::IncOccurrence to reduce confusing magic through consistency (,, see also ).
  • mut_arg can no longer be used to customize help and version arguments, instead disable them (Command::disable_help_flag, Command::disable_version_flag) and provide your own.
Top 5 of 35 that need code or config changes

clap publishes an official migration guide for version 4. It covers more than the release notes do.

Migrating to clap 4 ↗

Rust requirement changed in 4.6.0: 1.56.1 → 1.85.

Breaking26
name/version header was removed because we couldn't justify the space it occupied when.
--version
ArgAction::Set, ArgAction::SetTrue, and Arg::Action::SetFalse now conflict by default to be like ArgAction::StoreValue and ArgAction::IncOccurrences, requiring cmd.args_override_self(true) to…
ArgAction::SetArgAction::SetTrueArg::Action::SetFalseArgAction::StoreValueArgAction::IncOccurrencescmd.args_override_self(true)
By default, an Args default action is ArgAction::Set, rather than ArgAction::IncOccurrence to reduce confusing magic through consistency (,, see also ).
ArgArgAction::SetArgAction::IncOccurrence
mut_arg can no longer be used to customize help and version arguments, instead disable them (Command::disable_help_flag, Command::disable_version_flag) and provide your own.
mut_argCommand::disable_help_flagCommand::disable_version_flag
Removed lifetimes from Command, Arg, ArgGroup, and PossibleValue, assuming 'static. string feature flag will enable support for Strings.
CommandArgArgGroupPossibleValue'staticstring
Added default feature flags, help, usage and error-context, requiring adding them back in if default-features = false.
helpusageerror-context
(help) Make DeriveDisplayOrder the default and removed the setting.
DeriveDisplayOrdernext_display_order(None)
(help) name/version/author are removed by default from help output.
Command::help_template
Resolve behavior changes (see "subtle changes" under BREAKING CHANGES).
arg! now sets one of.
arg!ArgAction::SetTrueArgMatches::get_flagArgMatches::is_presentArgAction::CountArgMatches::get_count
arg!(--flag ) is now optional, instead of required.
.required(true)
(parser) Always fill in "" argument for external subcommands to make it easier to distinguish them from built-in commands.
(parser) Short flags now have higher precedence than hyphen values with Arg::allow_hyphen_values, to be consistent with Command::allow_hyphen_values.
Arg::allow_hyphen_valuesCommand::allow_hyphen_values
(parser) Arg::value_terminator must be its own argument on the CLI rather than being in a delimited list.
Arg::value_terminator
(help) Line wrapping of help is now behind the existing wrap_help feature flag, either enable it or hard code your wraps.
wrap_help
(help) Subcommand display order respects Command::next_display_order instead of DeriveDisplayOrder and using its own initial display order value.
Command::next_display_orderDeriveDisplayOrder
(help) Subcommands are now listed before arguments.
Command::help_template
(help) Help headings are now title cased, making any user-provided help headings inconsistent.
Command::help_templateArg::help_headingCommand::subcommand_help_heading
(help) "Command" is used as the section heading for subcommands and COMMAND for the value name.
COMMANDCommand::subcommand_help_headingArg::subcommand_value_name
(help) Whitespace in help output is now trimmed to ensure consistency regardless of how well a template matches the users needs.
(help) Indentation for second-line usage changed.
(env) Parse --help and --version like any ArgAction::SetTrue flag.
--help--versionArgAction::SetTrue
(derive) Leave Arg::id as verbatim casing, requiring updating of string references to other args like in conflicts_with or requires.
Arg::idverbatimconflicts_withrequires
(derive) Doc comments for ValueEnum variants will now show up in --help.
ValueEnum--help
(derive) When deriving Args, and ArgGroup is created using the type's name, reserving it for future use.
ArgsArgGroup
(derive) next_help_heading can now leak out of a #[clap(flatten)], like all other command settings.
next_help_heading#[clap(flatten)]
Platform3
Updates the minimum supported Rust version (MSRV) to 1.85.
Update MSRV to 1.74.
Update msrv to 1.70.0.
Deprecated6
Replacing the implicit behavior for args when parsing them with ArgAction.
ArgAction
Replacing various one-off forms of value validation with the ValueParser API.
ValueParserPathBuf
Replacing AppSettings and ArgSettings enums with getters/setters.
AppSettingsArgSettings
Clarifying terms and making them more consistent.
Run cargo check --features clap/deprecated and resolve all deprecation warnings.
At your leisure: resolve new deprecation notices.