{"record":{"id":"26d980572f368b38","repo":"pypa/pip","slug":"this-environment-is-externally-managed","errorCode":null,"errorMessage":"This environment is externally managed","messagePattern":"This environment is externally managed","errorType":"exception","errorClass":"ExternallyManagedEnvironment","httpStatus":null,"severity":"error","filePath":"src/pip/_internal/utils/misc.py","lineNumber":646,"sourceCode":"            \"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\n    raise ExternallyManagedEnvironment.from_config(marker)\n\n\ndef is_console_interactive() -> bool:\n    \"\"\"Is this console interactive?\"\"\"\n    return sys.stdin is not None and sys.stdin.isatty()\n\n\ndef hash_file(path: str, blocksize: int = 1 << 20) -> tuple[Any, int]:\n    \"\"\"Return (hash, length) for path using hashlib.sha256()\"\"\"\n\n    h = hashlib.sha256()\n    length = 0\n    with open(path, \"rb\") as f:\n        for block in read_chunks(f, size=blocksize):\n            length += len(block)\n            h.update(block)\n    return h, length\n","sourceCodeStart":628,"sourceCodeEnd":664,"githubUrl":"https://github.com/pypa/pip/blob/f399c3718970b1b0e2478dac5296eb62679a9b86/src/pip/_internal/utils/misc.py#L628-L664","documentation":"Raised as ExternallyManagedEnvironment by check_externally_managed (misc.py:646) when pip detects an EXTERNALLY-MANAGED marker file in the Python installation's stdlib directory and is not running inside a virtualenv. This implements PEP 668: system package managers (Debian, Fedora, Homebrew, etc.) place the marker to prevent pip from breaking the OS-managed Python environment. The exception provides diagnostic hints (use a venv, --break-system-packages, or pipx).","triggerScenarios":"check_externally_managed() is called at the start of an install operation. It returns early if running_under_virtualenv() (line 641), checks for os.path.join(sysconfig.get_path('stdlib'), 'EXTERNALLY-MANAGED') (line 643), and if that file exists, raises at line 646.","commonSituations":"Running `pip install` directly on system Python 3.11+ on Debian/Ubuntu, Fedora, Arch, Homebrew, or similar PEP 668-compliant distributions. Fresh OS installs where users haven't created a venv yet. CI images based on system Python.","solutions":["Create and activate a virtual environment: `python -m venv .venv && source .venv/bin/activate`, then install there.","Use pipx (`pipx install <pkg>`) for installing CLI applications into isolated environments.","Pass `--break-system-packages` to override the protection (not recommended, can break the OS Python).","Use `--target` to install into a user-specified directory without touching the system environment."],"exampleFix":"// before\n$ pip install requests\nerror: externally-managed-environment\n\n// after\n$ python -m venv .venv\n$ source .venv/bin/activate\n$ pip install requests","handlingStrategy":"validation","validationCode":"import os, sys, sysconfig, venv\n\ndef ensure_venv_or_warn():\n    \"\"\"Check if running in a venv or warn about externally-managed envs.\"\"\"\n    in_venv = sys.prefix != sys.base_prefix\n    marker = os.path.join(sysconfig.get_path('stdlib'), 'EXTERNALLY-MANAGED')\n    if not in_venv and os.path.isfile(marker):\n        print('System Python is externally managed. Create a venv first:')\n        print(f'  {sys.executable} -m venv .venv && source .venv/bin/activate')","typeGuard":"import sys, sysconfig, os\n\ndef is_externally_managed() -> bool:\n    \"\"\"True if the current Python is externally managed (PEP 668).\"\"\"\n    in_venv = sys.prefix != sys.base_prefix\n    if in_venv:\n        return False\n    marker = os.path.join(sysconfig.get_path('stdlib'), 'EXTERNALLY-MANAGED')\n    return os.path.isfile(marker)","tryCatchPattern":"from pip._internal.exceptions import ExternallyManagedEnvironment\n\ntry:\n    # pip install operation\n    pass\nexcept ExternallyManagedEnvironment:\n    # Fallback: create venv or use --break-system-packages\n    pass","preventionTips":["Always create and activate a venv before installing packages on system Python 3.11+.","Use pipx for standalone CLI tools to get isolated environments automatically.","In Dockerfiles, create a venv or use --break-system-packages deliberately."],"tags":["pep-668","externally-managed","virtualenv","system-python","security"],"backgroundTag":null,"analyzedSha":"f399c3718970b1b0e2478dac5296eb62679a9b86","analyzedAt":"2026-08-08T23:01:42.227Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}