pypa/pip · error · CommandError

To modify pip, please run the following command:\n{formatted

Error message

To modify pip, please run the following command:\n{formatted_command}

What it means

CommandError raised by protect_pip_from_modification on Windows when the user is trying to modify pip itself but invoked pip via a bare `pip ...` console-script entry point instead of `python -m pip`. On Windows, running pip.exe to upgrade pip can corrupt the running executable, so pip redirects to the module form.

Source

Thrown at src/pip/_internal/utils/misc.py:627

    """Protection of pip.exe from modification on Windows

    On Windows, any operation modifying pip should be run as:
        python -m pip ...
    """
    pip_names = [
        "pip",
        f"pip{sys.version_info.major}",
        f"pip{sys.version_info.major}.{sys.version_info.minor}",
    ]

    # See https://github.com/pypa/pip/issues/1299 for more discussion
    should_show_use_python_msg = (
        modifying_pip and WINDOWS and os.path.basename(sys.argv[0]) in pip_names
    )

    if should_show_use_python_msg:
        new_command = [sys.executable, "-m", "pip"] + sys.argv[1:]
        raise CommandError(
            "To modify pip, please run the following command:\n{}".format(
                " ".join(new_command)
            )
        )


def check_externally_managed() -> None:
    """Check whether the current environment is externally managed.

    If the ``EXTERNALLY-MANAGED`` config file is found, the current environment
    is considered externally managed, and an ExternallyManagedEnvironment is
    raised.
    """
    if running_under_virtualenv():
        return
    marker = os.path.join(sysconfig.get_path("stdlib"), "EXTERNALLY-MANAGED")
    if not os.path.isfile(marker):
        return

View on GitHub (pinned to d7d0d0a394)

Solutions

Run the exact command pip prints: `python -m pip install -U pip`.
Use `py -m pip ...` if you use the py launcher.
Upgrade pip as part of venv creation rather than via the pip.exe shim.

Example fix

# before (Windows)
pip install -U pip

# after
python -m pip install -U pip

Defensive patterns

Strategy: validation

Validate before calling

import sys, platform

def pip_self_upgrade_command():
    if platform.system() == 'Windows':
        return [sys.executable, '-m', 'pip', 'install', '-U', 'pip']
    return [sys.executable, '-m', 'pip', 'install', '-U', 'pip']  # safe everywhere
# always use this instead of bare `pip install -U pip`

Try / catch

try:
    run(['pip', 'install', '-U', 'pip'])
except CommandError as e:
    if 'To modify pip' in str(e):
        run([sys.executable, '-m', 'pip', 'install', '-U', 'pip'])
    else:
        raise

Prevention

Always upgrade pip via `python -m pip install -U pip`.
On Windows, prefer `py -m pip ...` with the py launcher.
Upgrade pip right after creating a venv, before other installs.

When it happens

Trigger: modifying_pip is True, WINDOWS, and os.path.basename(sys.argv[0]) is in {pip, pip3, pip3.11}. Concretely: `pip install -U pip` (or `pip install --upgrade pip`) run from the `pip.exe` script on Windows.

Common situations: Upgrading pip on Windows; CI on Windows runners that call `pip install -U pip`; bootstrapping a fresh Windows venv where the first thing you do is upgrade pip via the shim.

Related errors

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