Add docs/python/pip-env-vars.md

docs/python/pip-env-vars.md

@@ -0,0 +1,85 @@
+# Why `pip install` Fails: Python Externally Managed Environments
+
+If you are seeing the error `error: externally-managed-environment` on Linux (Debian 12, Ubuntu 24.04, etc.), this guide explains why it happens and how to fix it correctly.
+
+## 1. The "Why": Protecting Your Operating System
+This error is a safety feature introduced by **PEP 668**. 
+
+On Linux, **Python is part of the Operating System**. Critical system tools (like `apt`, `dnf`, network managers, and display servers) rely on specific versions of Python libraries installed by the OS package manager.
+
+* **The Old Way:** `pip` allowed you to install/upgrade packages globally. This often overwrote versions the OS needed, leading to "broken" systems where system updates or tools would fail.
+* **The New Way:** `pip` now detects if the environment is managed by the OS and refuses to touch it unless you use an isolated environment.
+
+---
+
+## 2. The Solution: Three Ways to Install Packages
+
+There are three correct ways to install Python packages depending on your goal.
+
+### Method A: For Development (Projects & Scripts)
+**Best for:** Writing code, learning Python, or running specific projects.
+**Tool:** `venv` (Virtual Environment)
+
+This creates a self-contained folder (`.venv`) with its own Python and libraries, completely isolated from the system.
+
+1.  **Create the environment** (inside your project folder):
+    ```bash
+    python3 -m venv .venv
+    ```
+    *(Note: If this fails, run `sudo apt install python3-venv` first).*
+
+2.  **Activate the environment**:
+    ```bash
+    source .venv/bin/activate
+    ```
+    *(Your terminal prompt should now show `(.venv)`).*
+
+3.  **Install your package**:
+    ```bash
+    pip install pyusb
+    ```
+
+*To exit the environment later, just type `deactivate`.*
+
+### Method B: For Standalone Applications
+**Best for:** CLI tools you want to run from anywhere (e.g., `youtube-dl`, `black`, `ansible`).
+**Tool:** `pipx`
+
+`pipx` creates a managed virtual environment for each application automatically and links the executable to your global path.
+
+1.  **Install pipx** (once):
+    ```bash
+    sudo apt install pipx
+    pipx ensurepath
+    ```
+2.  **Install the tool**:
+    ```bash
+    pipx install package-name
+    ```
+
+### Method C: For System-Wide Libraries
+**Best for:** When a script *must* use the system Python and you don't need a specific newer version.
+**Tool:** `apt` (or your OS package manager)
+
+The OS maintainers package Python libraries that are guaranteed to be compatible with your system.
+
+1.  **Search for the package**:
+    ```bash
+    apt search python3-pyusb
+    ```
+2.  **Install it**:
+    ```bash
+    sudo apt install python3-pyusb
+    ```
+
+---
+
+## 3. Summary Cheat Sheet
+
+| Goal | Do NOT run | **DO Run** |
+| :--- | :--- | :--- |
+| **Coding/Project** | `pip install pyusb` | **`python3 -m venv .venv`** (then pip install) |
+| **Command Line Tool** | `pip install youtube-dl` | **`pipx install youtube-dl`** |
+| **System Requirement** | `sudo pip install pyusb` | **`sudo apt install python3-pyusb`** |
+
+> **⚠️ Warning:** The error message mentions the flag `--break-system-packages`. **Avoid using this.** It allows you to override the safety check, but it carries a high risk of breaking your OS updates or system tools in the future.