pypa/pip · error · CommandError

unknown command "{cmd_name}" - maybe you meant "{guess}"

Error message

unknown command "{cmd_name}" - maybe you meant "{guess}"

What it means

Raised by parse_command() in main_parser.py:129 when the first non-option argument is not a recognized pip subcommand. The error includes a 'did you mean?' suggestion from get_similar_commands() using fuzzy matching (difflib) against the known commands_dict. If no close match is found, the suggestion portion is omitted.

Source

Thrown at src/pip/_internal/cli/main_parser.py:129

        sys.stdout.write(os.linesep)
        sys.exit()

    # pip || pip help -> print_help()
    if not args_else or (args_else[0] == "help" and len(args_else) == 1):
        parser.print_help()
        sys.exit()

    # the subcommand name
    cmd_name = args_else[0]

    if cmd_name not in commands_dict:
        guess = get_similar_commands(cmd_name)

        msg = [f'unknown command "{cmd_name}"']
        if guess:
            msg.append(f'maybe you meant "{guess}"')

        raise CommandError(" - ".join(msg))

    # all the args without the subcommand
    cmd_args = args[:]
    cmd_args.remove(cmd_name)

    return cmd_name, cmd_args

View on GitHub (pinned to d7d0d0a394)

Solutions

1. Check the spelling against known commands: `pip help` lists all commands.
2. If a suggestion is given, use the suggested command.
3. Update pip to the latest version if the command might be new.

Example fix

# before
pip instal numpy

# after
pip install numpy

from difflib import get_close_matches
KNOWN_COMMANDS = ['install', 'download', 'uninstall', 'freeze', 'list', 'show', 'search', 'wheel', 'hash', 'completion', 'help', 'index', 'inspect']
def validate_command_name(name):
    if name in KNOWN_COMMANDS:
        return True
    matches = get_close_matches(name, KNOWN_COMMANDS, n=1, cutoff=0.6)
    return False, (matches[0] if matches else None)

from pip._internal.exceptions import CommandError
try:
    # pip <cmd> ...
except CommandError as e:
    if 'unknown command' in str(e):
        # parse suggestion and retry with corrected command

When it happens

Trigger: Calling `pip instal foo` (typo for 'install'), `pip donwload foo` (typo for 'download'), `pip freese` (typo for 'freeze'), or any unrecognized first argument that isn't a valid pip command.

Common situations: Typos in pip subcommands. Using a command from a different package manager (e.g., `pip add` from npm/yarn). Running an older pip that doesn't have a newer command. Shell autocompletion inserting the wrong command.

Related errors

• unknown command "{cmd_name}" - maybe you meant "{guess}"
• Cannot use '--only-dependencies' in combination with {confli
• When restricting platform and interpreter constraints using
• Can not use any platform or abi specific options unless inst
• Platform and interpreter constraints using --python-version,

AI-assisted analysis of pypa/pip@d7d0d0a394 (2026-08-04). Data as JSON: /data/errors/a3c6eb7d8e298811.json. Report an issue: GitHub.