{"record":{"id":"eeb8047d898be448","repo":"pypa/pip","slug":"to-modify-pip-please-run-the-following-command","errorCode":null,"errorMessage":"To modify pip, please run the following command:\n{}","messagePattern":"To modify pip, please run the following command:\n(.+?)","errorType":"exception","errorClass":"CommandError","httpStatus":null,"severity":"error","filePath":"src/pip/_internal/utils/misc.py","lineNumber":627,"sourceCode":"    \"\"\"Protection of pip.exe from modification on Windows\n\n    On Windows, any operation modifying pip should be run as:\n        python -m pip ...\n    \"\"\"\n    pip_names = [\n        \"pip\",\n        f\"pip{sys.version_info.major}\",\n        f\"pip{sys.version_info.major}.{sys.version_info.minor}\",\n    ]\n\n    # See https://github.com/pypa/pip/issues/1299 for more discussion\n    should_show_use_python_msg = (\n        modifying_pip and WINDOWS and os.path.basename(sys.argv[0]) in pip_names\n    )\n\n    if should_show_use_python_msg:\n        new_command = [sys.executable, \"-m\", \"pip\"] + sys.argv[1:]\n        raise CommandError(\n            \"To modify pip, please run the following command:\\n{}\".format(\n                \" \".join(new_command)\n            )\n        )\n\n\ndef check_externally_managed() -> None:\n    \"\"\"Check whether the current environment is externally managed.\n\n    If the ``EXTERNALLY-MANAGED`` config file is found, the current environment\n    is considered externally managed, and an ExternallyManagedEnvironment is\n    raised.\n    \"\"\"\n    if running_under_virtualenv():\n        return\n    marker = os.path.join(sysconfig.get_path(\"stdlib\"), \"EXTERNALLY-MANAGED\")\n    if not os.path.isfile(marker):\n        return","sourceCodeStart":609,"sourceCodeEnd":645,"githubUrl":"https://github.com/pypa/pip/blob/f399c3718970b1b0e2478dac5296eb62679a9b86/src/pip/_internal/utils/misc.py#L609-L645","documentation":"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.","triggerScenarios":"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.","commonSituations":"Windows users following Linux/macOS tutorials that say `pip install --upgrade pip`. CI runners on Windows. Docker Windows containers.","solutions":["Run `python -m pip install --upgrade pip` instead of `pip install --upgrade pip` (the error message provides the exact command).","Ensure sys.executable resolves to the correct Python interpreter before running the upgrade.","If using a virtualenv, activate it first so `python` points to the venv's interpreter.","As a last resort on Windows, download get-pip.py and run `python get-pip.py --upgrade`."],"exampleFix":"// before\nC:\\> pip install --upgrade pip\n\n// after\nC:\\> python -m pip install --upgrade pip","handlingStrategy":"validation","validationCode":"import sys, subprocess\n\ndef safe_pip_upgrade():\n    \"\"\"Upgrade pip using python -m pip on all platforms.\"\"\"\n    subprocess.run(\n        [sys.executable, '-m', 'pip', 'install', '--upgrade', 'pip'],\n        check=True,\n    )\n\n# Always use sys.executable -m pip instead of bare pip for self-upgrade","typeGuard":"import sys, os\n\ndef is_windows_pip_exe() -> bool:\n    \"\"\"True if running on Windows via pip.exe (risky for self-modification).\"\"\"\n    return (\n        os.name == 'nt'\n        and os.path.basename(sys.argv[0]) in ('pip', f'pip{sys.version_info.major}')\n    )","tryCatchPattern":null,"preventionTips":["Always upgrade pip with `python -m pip install --upgrade pip`, never bare `pip install`.","Cross-platform install scripts should always prefix with sys.executable -m pip.","On Windows CI, ensure the venv is activated so `python` points to the correct interpreter."],"tags":["windows","self-upgrade","pip-modification","command-error"],"backgroundTag":null,"analyzedSha":"f399c3718970b1b0e2478dac5296eb62679a9b86","analyzedAt":"2026-08-08T23:01:42.227Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}