Initial commit

skills/django-setup/troubleshooting/venv-issues.md

@@ -0,0 +1,376 @@
+# Troubleshooting: Virtual Environment Issues
+
+[← Back to main skill](../SKILL.md)
+
+---
+
+## Issue: `ensurepip is not available` {#ensurepip}
+
+**Full error:**
+```
+Error: Command '[...]/python3', '-Im', 'ensurepip', '--upgrade', '--default-pip']' returned non-zero exit status 1
+```
+
+### Solutions:
+
+**Ubuntu/Debian:**
+```bash
+sudo apt install python3.13-venv python3.13-distutils -y
+```
+
+**macOS (Homebrew):**
+```bash
+brew reinstall python@3.13
+```
+
+**Windows:**
+- Reinstall Python with "pip" option checked
+- Or download get-pip.py: https://bootstrap.pypa.io/get-pip.py
+
+---
+
+## Issue: PowerShell Execution Policy {#powershell-execution-policy}
+
+**Error:**
+```
+venv\Scripts\Activate.ps1 cannot be loaded because running scripts is disabled on this system
+```
+
+### Solution:
+
+**Allow scripts for current user:**
+```powershell
+Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
+```
+
+**Then retry activation:**
+```powershell
+venv\Scripts\Activate.ps1
+```
+
+**Verify policy:**
+```powershell
+Get-ExecutionPolicy -List
+```
+
+---
+
+## Issue: Virtual Environment Not Activating
+
+**Symptoms:**
+- No `(venv)` prefix in prompt
+- `which python` still points to system Python
+
+### Solutions:
+
+**macOS/Linux - Check activation command:**
+```bash
+source venv/bin/activate  # Correct
+. venv/bin/activate       # Also works
+bash venv/bin/activate    # Wrong - don't use bash
+```
+
+**Windows - Use correct script:**
+```powershell
+# PowerShell
+venv\Scripts\Activate.ps1
+
+# Command Prompt
+venv\Scripts\activate.bat
+
+# Git Bash
+source venv/Scripts/activate
+```
+
+**Verify activation:**
+```bash
+which python  # Should point to venv/bin/python
+echo $VIRTUAL_ENV  # Should show venv path
+```
+
+---
+
+## Issue: Permission Denied on Activation {#permission-denied}
+
+**Error (macOS/Linux):**
+```
+bash: venv/bin/activate: Permission denied
+```
+
+### Solution:
+
+**Make script executable:**
+```bash
+chmod +x venv/bin/activate
+source venv/bin/activate
+```
+
+**Or recreate venv:**
+```bash
+rm -rf venv
+python3 -m venv venv
+```
+
+---
+
+## Issue: `venv` Module Not Found
+
+**Error:**
+```
+No module named venv
+```
+
+### Solutions:
+
+**Ubuntu/Debian:**
+```bash
+sudo apt install python3.13-venv -y
+```
+
+**Fedora/RHEL:**
+```bash
+sudo dnf install python3.13-venv -y
+```
+
+**macOS:**
+```bash
+# Reinstall Python via Homebrew
+brew reinstall python@3.13
+
+# Or install from python.org
+```
+
+**Windows:**
+- Usually included by default
+- Reinstall Python if missing
+
+---
+
+## Issue: Wrong Python Version in venv
+
+**Symptom:**
+```bash
+(venv) $ python --version
+Python 3.8.10  # But you wanted 3.13!
+```
+
+### Solution:
+
+**Delete and recreate with specific version:**
+```bash
+deactivate  # If currently activated
+rm -rf venv
+
+# Specify exact Python version
+python3.13 -m venv venv  # macOS/Linux
+py -3.13 -m venv venv    # Windows
+```
+
+**Verify before activating:**
+```bash
+venv/bin/python --version  # Check version first
+source venv/bin/activate    # Then activate
+```
+
+---
+
+## Issue: Can't Deactivate venv
+
+**Symptom:**
+- `deactivate` command doesn't work
+- Still see `(venv)` in prompt
+
+### Solutions:
+
+**Try deactivate function:**
+```bash
+deactivate
+```
+
+**If that fails, just close terminal:**
+- Exit terminal/shell
+- Open new terminal
+- venv won't be active in new session
+
+**Or manually unset variables:**
+```bash
+unset VIRTUAL_ENV
+export PATH="$OLD_PATH"
+```
+
+---
+
+## Issue: venv Created in Wrong Location
+
+**Symptom:**
+- venv created in home directory instead of project
+- venv in system location
+
+### Solution:
+
+**Delete misplaced venv:**
+```bash
+rm -rf ~/venv  # Or wherever it was created
+```
+
+**Navigate to project first:**
+```bash
+cd /path/to/your/project
+pwd  # Verify you're in correct directory
+python3 -m venv venv  # Now create here
+```
+
+---
+
+## Issue: `pip` Not Found After Activation
+
+**Error:**
+```
+(venv) $ pip --version
+pip: command not found
+```
+
+### Solutions:
+
+**Use `python -m pip` instead:**
+```bash
+python -m pip --version
+python -m pip install <package>
+```
+
+**Reinstall pip in venv:**
+```bash
+curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
+python get-pip.py
+rm get-pip.py
+```
+
+**Or recreate venv:**
+```bash
+deactivate
+rm -rf venv
+python3 -m venv venv --clear
+```
+
+---
+
+## Issue: venv Taking Too Much Space
+
+**Symptom:**
+- venv folder is several GB
+- Too many cached packages
+
+### Solutions:
+
+**Clear pip cache:**
+```bash
+pip cache purge
+```
+
+**Remove unnecessary packages:**
+```bash
+pip list  # See what's installed
+pip uninstall <package>
+```
+
+**Use `--no-cache-dir` when installing:**
+```bash
+pip install --no-cache-dir Django
+```
+
+**Typical venv sizes:**
+- Minimal Django: ~100-200 MB
+- Full-featured project: ~500 MB - 1 GB
+- If >2 GB, something is wrong
+
+---
+
+## Issue: Can't Delete venv Folder
+
+**Windows error:**
+```
+Access denied
+File in use
+```
+
+### Solutions:
+
+**Deactivate first:**
+```bash
+deactivate
+```
+
+**Close all terminals/IDEs using that folder**
+
+**Windows - use PowerShell as Admin:**
+```powershell
+Remove-Item -Recurse -Force venv
+```
+
+**Or use File Explorer:**
+- Right-click venv folder
+- Properties → Security → Advanced
+- Take ownership
+- Delete
+
+---
+
+## Issue: IDE Not Recognizing venv
+
+**VS Code, PyCharm not using venv Python**
+
+### Solutions:
+
+**VS Code:**
+1. Press `Ctrl+Shift+P` (or `Cmd+Shift+P` on Mac)
+2. Type "Python: Select Interpreter"
+3. Choose `./venv/bin/python`
+
+**PyCharm:**
+1. File → Settings (or Preferences on Mac)
+2. Project → Python Interpreter
+3. Click gear icon → Add
+4. Select "Existing environment"
+5. Browse to `venv/bin/python`
+
+---
+
+## Best Practices to Avoid Issues
+
+✅ **Always activate before installing packages**
+```bash
+source venv/bin/activate  # Activate first
+pip install Django        # Then install
+```
+
+✅ **One venv per project**
+```
+project1/
+  └── venv/
+project2/
+  └── venv/
+```
+
+✅ **Don't commit venv to git**
+```gitignore
+venv/
+.venv/
+env/
+ENV/
+```
+
+✅ **Document Python version in README**
+```markdown
+## Requirements
+- Python 3.13+
+```
+
+✅ **Use requirements.txt**
+```bash
+pip freeze > requirements.txt
+# Others can: pip install -r requirements.txt
+```
+
+---
+
+[← Back to django-project-setup](../SKILL.md)