From 919f7284a97fe0d74c407534d8bc081f342b440e Mon Sep 17 00:00:00 2001
From: FSSCoding <brett@foxsoftwaresolutions.com.au>
Date: Sat, 6 Sep 2025 17:09:46 +1000
Subject: [PATCH] Add robust installation method for
 externally-managed-environment

- Use python -m pip instead of pip for better virtual environment handling
- Add troubleshooting section for PEP 668 externally-managed-environment errors
- Include --break-system-packages workaround when needed in virtual environments

Addresses system-level pip restrictions that block installation even in venvs.
---
 README.md | 17 +++++++++++++++--
 1 file changed, 15 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index d6a439a..7fcdeca 100644
--- a/README.md
+++ b/README.md
@@ -89,8 +89,21 @@ cd Fss-Mini-Rag
 python3 -m venv .venv
 source .venv/bin/activate    # Linux/macOS
 # .venv\Scripts\activate     # Windows
-pip install -r requirements.txt
-pip install .
+
+# Use python -m pip for reliability (handles externally-managed-environment errors)
+python -m pip install -r requirements.txt
+python -m pip install .
+```
+
+**If you get "externally-managed-environment" error:**
+```bash
+# Verify virtual environment is active
+which python  # Should show .venv/bin/python
+python -m pip --version  # Should show .venv path
+
+# If still failing, use override (safe in virtual environment)
+python -m pip install -r requirements.txt --break-system-packages
+python -m pip install . --break-system-packages
 ```
 
 **Step 2: Start Using**