{"id":"f44e05f18eff5586","repo":"pypa/pip","slug":"to-modify-pip-please-run-the-following-command-n","errorCode":null,"errorMessage":"To modify pip, please run the following command:\\n{formatted_command}","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/d7d0d0a39494e28ec1c407bd0680e4a4d1067791/src/pip/_internal/utils/misc.py#L609-L645","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"# before (Windows)\npip install -U pip\n\n# after\npython -m pip install -U pip","handlingStrategy":"validation","validationCode":"import sys, platform\n\ndef pip_self_upgrade_command():\n    if platform.system() == 'Windows':\n        return [sys.executable, '-m', 'pip', 'install', '-U', 'pip']\n    return [sys.executable, '-m', 'pip', 'install', '-U', 'pip']  # safe everywhere\n# always use this instead of bare `pip install -U pip`","typeGuard":null,"tryCatchPattern":"try:\n    run(['pip', 'install', '-U', 'pip'])\nexcept CommandError as e:\n    if 'To modify pip' in str(e):\n        run([sys.executable, '-m', 'pip', 'install', '-U', 'pip'])\n    else:\n        raise","preventionTips":["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."],"tags":["pip","windows","self-upgrade","venv","command-error"],"analyzedSha":"d7d0d0a39494e28ec1c407bd0680e4a4d1067791","analyzedAt":"2026-08-04T20:55:04.259Z","schemaVersion":2}