pypa/pip · error · CommandError

unknown command " " - maybe you meant

Error message

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

What it means

Raised by `pip help` when the requested command name does not exist. HelpCommand.run at help.py:28 looks up cmd_name in commands_dict; on miss it calls get_similar_commands to find a likely match and raises a CommandError with 'unknown command' plus an optional 'maybe you meant' suggestion.

Solutions

1. Check the suggestion in the message — 'maybe you meant "install"'.
2. Run `pip help` (no args) or `pip --help` to list all available commands.
3. Correct the command name and retry.

Example fix

// before
pip help instal
// after
pip help install

# Validate the command name before pip help
from pip._internal.commands import commands_dict, get_similar_commands

def validate_help_cmd(name):
    if name not in commands_dict:
        guess = get_similar_commands(name)
        raise ValueError("unknown command %r%s" % (name, ("; did you mean %r?" % guess) if guess else ""))
    return True

When it happens

Trigger: Invoking `pip help <bad-name>` where <bad-name> is not a registered pip command (e.g. `pip help instal`, `pip help instal`). Levenshtein-style suggestions are attempted.

Common situations: Typos, deprecated command names, or confusion between pip and another tool's vocabulary. The suggestion helps catch simple misspellings.

Related errors

• Can not combine '--user' and '--prefix' as they imply…
• Can not combine '--user' and '--target'
• Can not perform a '--user' install. User site-packages are…
• Got unexpected number of arguments, expected
• Need exactly one file to operate upon (--user, --site…

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

Appendix: source

Thrown at src/pip/_internal/commands/help.py:35

            commands_dict,
            create_command,
            get_similar_commands,
        )

        try:
            # 'pip help' with no args is handled by pip.__init__.parseopt()
            cmd_name = args[0]  # the command we need help for
        except IndexError:
            return SUCCESS

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

        command = create_command(cmd_name)
        command.parser.print_help()

        return SUCCESS

View on GitHub (pinned to f399c37189)