pypa/pip · error · CommandError

unknown command "{cmd_name}"

Error message

unknown command "{cmd_name}"

What it means

Raised as CommandError by parse_command (main_parser.py:130) when the first non-option token is not a registered subcommand in commands_dict. Pip splits general options from the rest (line 81), takes args_else[0] as the subcommand (line 121), and at line 123 checks membership; on miss it calls get_similar_commands (line 124) to suggest a close match (e.g. 'install' for 'isntall'). The message lists the typo and, if available, a 'maybe you meant' hint.

Source

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

        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 f399c37189)

Solutions

1. Correct the subcommand spelling; run `pip help` to list valid commands.
2. If a 'maybe you meant' hint is shown, use the suggested command.
3. Upgrade/downgrade pip to match the documentation the command came from if a renamed command is involved.

Example fix

# before
pip isntall requests
# after
pip install requests

# Validate the subcommand against pip's registry before dispatching.
from pip._internal.commands import commands_dict, get_similar_commands
def validate_subcommand(name):
    if name not in commands_dict:
        guess = get_similar_commands(name)
        raise ValueError(f'unknown command "{name}"' + (f', did you mean "{guess}"?' if guess else ''))
    return True

When it happens

Trigger: `pip isntall requests`, `pip instal requests`, or any misspelled/renamed subcommand.

Common situations: Typing pip commands quickly; using a subcommand that was removed or renamed in a newer pip; copy-pasting a command from docs that uses a different pip version's command name.

Related errors

• 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,
• --build-constraint cannot be used with --no-build-isolation.

AI-assisted analysis of pypa/pip@f399c37189 (2026-08-08). Data as JSON: /api/errors/5e9cd7b455e87708. Report an issue: GitHub.