How do I prevent pip:UNKNOWN_COMMAND in CI?

Prefer `python -m pip ...` so the right pip is used for the active interpreter. Use `pip help ` to confirm syntax before scripting it. Use virtual environments so upgrades don't affect system Python.

How can I manually validate pip:UNKNOWN_COMMAND?

See available commands: `python -m pip help`. Check which pip you're using: `python -m pip --version`.

ERROR: unknown command "update" (and "upgrade")

Q: What does pip:UNKNOWN_COMMAND mean?

pip does not have `update` or `upgrade` subcommands. Upgrading packages is done with `pip install --upgrade ...`.

Fix it fast

Most likely: The command uses package-manager verbs that pip does not have. pip upgrades packages with install --upgrade, not pip update or pip upgrade.

Confirm this is your error

Match the output and confirm you are troubleshooting the same failure.

ERROR: unknown command "update"
ERROR: unknown command "upgrade"

Check the cause

Run focused checks to identify what is failing in this environment.

python -m pip --version
python -m pip help
python -m pip list --outdated

Apply the safe fix

Use the smallest safe change that addresses the confirmed cause.

# Upgrade one package.
python -m pip install --upgrade <package>

# Upgrade pip itself in the active environment.
python -m pip install --upgrade pip

# See what is outdated before changing anything.
python -m pip list --outdated

Verify it works

Repeat the relevant checks and confirm the original error is gone.

python -m pip show <package>
python -m pip list --outdated

Avoid unsafe shortcuts

Keep security and data protections in place while troubleshooting.

Do not copy apt update or apt upgrade patterns into pip commands.
Do not upgrade system Python packages when the project should be using a virtual environment.
Do not call bare pip in scripts when python -m pip makes the target interpreter explicit.

What pip Is Rejecting

pip does not have update or upgrade subcommands. Upgrading packages is done with pip install --upgrade ....

Fix the command

To upgrade a package with python -m pip install --upgrade <package>, to upgrade pip itself with python -m pip install --upgrade pip, and to review what would be upgraded with python -m pip list --outdated.

Check the exact command and local inputs

See available commands with python -m pip help, and check which pip you're using with python -m pip --version.

Why the Command Was Rejected

Usually this comes down to you ran pip update ... or pip upgrade ..., but those are not valid pip subcommands, or you expected pip to behave like an OS package manager.

Re-run the Minimal Correct Command

Run python -m pip list --outdated and confirm the package is no longer listed (if it was upgraded), and re-run your install/upgrade command and confirm pip no longer reports an unknown subcommand.

How pip validates the command before it runs

This is the part worth understanding if the quick fix did not hold. It explains what pip is trying to do at the moment the error appears.

pip uses subcommands like install, uninstall, list, and show.

Package upgrades are performed by re-running install with the --upgrade flag.

Upgrading pip itself is also performed with install --upgrade pip in the active environment.

Avoid Command and Config Drift

To prevent this, prefer python -m pip ... so the right pip is used for the active interpreter, use pip help <command> to confirm syntax before scripting it, and use virtual environments so upgrades don't affect system Python.

Docs and source code

github.com/pypa/pip/blob/25.3/src/pip/_internal/cli/main_parser.py

pip raises a CommandError with unknown command "..." when the first CLI argument is not a valid subcommand. - GitHub

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