pypa/pip · error · CommandError

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

Error message

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

What it means

Raised as CommandError by protect_pip_from_modification_on_windows (misc.py:627) on Windows when the user invokes pip to modify pip itself (upgrade/uninstall) using the pip.exe entry point rather than `python -m pip`. On Windows, pip.exe locks its own executable, so modifying pip in-place can corrupt or fail the installation. The error message provides the correct command using `python -m pip` to avoid the self-modification problem.

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

Solutions

1. Run `python -m pip install --upgrade pip` instead of `pip install --upgrade pip` (the error message provides the exact command).
2. Ensure sys.executable resolves to the correct Python interpreter before running the upgrade.
3. If using a virtualenv, activate it first so `python` points to the venv's interpreter.
4. As a last resort on Windows, download get-pip.py and run `python get-pip.py --upgrade`.

Example fix

// before
C:\> pip install --upgrade pip

// after
C:\> python -m pip install --upgrade pip

import sys, subprocess

def safe_pip_upgrade():
    """Upgrade pip using python -m pip on all platforms."""
    subprocess.run(
        [sys.executable, '-m', 'pip', 'install', '--upgrade', 'pip'],
        check=True,
    )

# Always use sys.executable -m pip instead of bare pip for self-upgrade

import sys, os

def is_windows_pip_exe() -> bool:
    """True if running on Windows via pip.exe (risky for self-modification)."""
    return (
        os.name == 'nt'
        and os.path.basename(sys.argv[0]) in ('pip', f'pip{sys.version_info.major}')
    )

When it happens

Trigger: Running `pip install --upgrade pip` (or `pip uninstall pip`) on Windows where sys.argv[0] is pip.exe (basename in pip_names list at line 614-618), modifying_pip is True, and WINDOWS is True. The check at lines 621-623 evaluates True and raises.

Common situations: Windows users following Linux/macOS tutorials that say `pip install --upgrade pip`. CI runners on Windows. Docker Windows containers.

Related errors

• Python executable failed to copy to {python_executable}
• 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,

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