Python "argparse: error: unrecognized arguments" in CI

argparse prints error: unrecognized arguments: ... and exits with status 2 when the command line contains a flag or positional it does not define. In CI this aborts the job because exit 2 is non-zero.

What this error means

A CLI invocation fails with "usage: ... error: unrecognized arguments: --foo" and the step exits with code 2.

prog: error: unrecognized arguments: --new-flag value

Common causes

The CI command passes a flag the parser version does not know

A workflow was updated to pass a new option, but the installed tool version predates it.

A subcommand argument placed before the subcommand

argparse with subparsers only accepts a subcommand-specific flag after the subcommand name.

How to fix it

Align the flags with the parser definition

1. Run the command with --help to list the flags the installed version accepts.
2. Add the flag to the parser with add_argument, or remove it from the CI invocation.
3. For subparsers, place subcommand flags after the subcommand name.

parser.add_argument("--new-flag", help="...")

How to prevent it

• Pin the CLI tool version so its accepted flags are stable.
• Keep the parser definition and the CI invocation in sync.
• Add a smoke test that runs the CLI with --help.

Related guides