pypa/pip · warning · CommandError

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

Error message

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

What it means

Raised by HelpCommand.run when 'pip help <cmd>' is invoked with a command name that is not registered in commands_dict. pip computes the closest match via get_similar_commands (difflib-based) and, if a suggestion exists, appends 'maybe you meant "<guess>"'.

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

Solutions

1. Use the suggested command if one is offered.
2. Run 'pip help' with no argument to list all available commands.
3. Check spelling against 'pip list' of commands or the docs.

Example fix

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

from difflib import get_close_matches
known = {"install", "download", "uninstall", "list", "show", "freeze", "search", "wheel", "cache", "config", "help"}
if cmd not in known:
    guess = get_close_matches(cmd, known, n=1)
    raise SystemExit(f"unknown command {cmd!r}" + (f", did you mean {guess[0]!r}?" if guess else ""))

When it happens

Trigger: Running 'pip help instal', 'pip help isntall', 'pip help frozenset' - any token that is not a real pip command. help.py:28 checks commands_dict and help.py:29 computes a guess.

Common situations: Typos; tab-completion off; scripts referencing a renamed/removed command; users coming from another package manager's vocabulary.

Related errors

• unknown command "{cmd_name}" - maybe you meant "{guess}"
• --require-hashes and --no-require-hashes are mutually exclus
• You must give at least one requirement to {name} (maybe you
• You must give at least one requirement to {name} (see "pip h
• Too many arguments

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