Initial commit

skills/django-setup/troubleshooting/pip-problems.md

@@ -0,0 +1,386 @@
+# Troubleshooting: pip Problems
+
+[← Back to main skill](../SKILL.md)
+
+---
+
+## Issue: `pip: command not found` {#pip-not-found}
+
+**After activating venv, pip doesn't work**
+
+### Solutions:
+
+**Use `python -m pip` instead:**
+```bash
+python -m pip --version
+python -m pip install Django
+python -m pip install --upgrade pip
+```
+
+**Ensure venv is activated:**
+```bash
+source venv/bin/activate  # macOS/Linux
+venv\Scripts\activate     # Windows
+```
+
+**Reinstall pip in venv:**
+```bash
+python -m ensurepip --upgrade
+```
+
+---
+
+## Issue: `pip install` Requires sudo
+
+**Error:**
+```
+ERROR: Could not install packages due to an OSError: [Errno 13] Permission denied
+```
+
+### Solution:
+
+**❌ NEVER use sudo with pip!**
+
+**✅ Use virtual environment instead:**
+```bash
+# Create and activate venv first
+python3 -m venv venv
+source venv/bin/activate
+
+# Now install without sudo
+pip install Django
+```
+
+**Why no sudo:**
+- Pollutes system Python
+- Breaks system tools
+- Security risk
+- Conflicts with package manager
+
+---
+
+## Issue: SSL Certificate Errors
+
+**Error:**
+```
+SSL: CERTIFICATE_VERIFY_FAILED
+```
+
+### Solutions:
+
+**macOS - Install certificates:**
+```bash
+/Applications/Python\ 3.13/Install\ Certificates.command
+```
+
+**Or install certifi:**
+```bash
+pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org certifi
+```
+
+**Ubuntu/Debian:**
+```bash
+sudo apt install ca-certificates
+sudo update-ca-certificates
+```
+
+**Temporary workaround (not recommended):**
+```bash
+pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org Django
+```
+
+---
+
+## Issue: pip is Outdated
+
+**Warning:**
+```
+WARNING: You are using pip version X.X.X; however, version Y.Y.Y is available.
+```
+
+### Solution:
+
+**Upgrade pip:**
+```bash
+python -m pip install --upgrade pip
+```
+
+**If that fails:**
+```bash
+curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
+python get-pip.py
+rm get-pip.py
+```
+
+---
+
+## Issue: Package Installation Fails
+
+**Error:**
+```
+ERROR: Could not find a version that satisfies the requirement <package>
+```
+
+### Solutions:
+
+**Check package name spelling:**
+```bash
+# Wrong
+pip install django-rest-framework
+
+# Correct
+pip install djangorestframework
+```
+
+**Check Python version compatibility:**
+```bash
+python --version  # Some packages require Python 3.11+
+```
+
+**Try older package version:**
+```bash
+pip install "Django<5.0"  # Install Django 4.x
+```
+
+**Update pip and setuptools:**
+```bash
+pip install --upgrade pip setuptools wheel
+```
+
+---
+
+## Issue: Conflicting Dependencies
+
+**Error:**
+```
+ERROR: package-a 1.0 has requirement package-b>=2.0, but you'll have package-b 1.5
+```
+
+### Solutions:
+
+**Let pip resolve (pip 20.3+):**
+```bash
+pip install --upgrade <package>
+```
+
+**Install specific compatible versions:**
+```bash
+pip install package-a package-b==2.0
+```
+
+**Use pip-tools for dependency management:**
+```bash
+pip install pip-tools
+# Create requirements.in with your deps
+pip-compile requirements.in
+pip-sync requirements.txt
+```
+
+**Nuclear option - recreate venv:**
+```bash
+deactivate
+rm -rf venv
+python3 -m venv venv
+source venv/bin/activate
+pip install -r requirements.txt
+```
+
+---
+
+## Issue: Building Wheels Failed
+
+**Error:**
+```
+Failed building wheel for <package>
+```
+
+### Solutions:
+
+**Install build dependencies:**
+
+**macOS:**
+```bash
+xcode-select --install
+brew install openssl
+```
+
+**Ubuntu/Debian:**
+```bash
+sudo apt install python3-dev build-essential libssl-dev libffi-dev -y
+```
+
+**Fedora/RHEL:**
+```bash
+sudo dnf install python3-devel gcc openssl-devel libffi-devel -y
+```
+
+**Windows:**
+- Install Microsoft C++ Build Tools
+- Download from: https://visualstudio.microsoft.com/visual-cpp-build-tools/
+
+**Use pre-built wheels:**
+```bash
+pip install --only-binary :all: <package>
+```
+
+---
+
+## Issue: `externally-managed-environment` Error
+
+**Error (Python 3.11+ on some Linux distros):**
+```
+error: externally-managed-environment
+This environment is externally managed
+```
+
+### Solution:
+
+**✅ Use virtual environment (recommended):**
+```bash
+python3 -m venv venv
+source venv/bin/activate
+pip install Django
+```
+
+**Or use `--break-system-packages` (not recommended):**
+```bash
+pip install --break-system-packages Django  # ⚠️ Use at own risk
+```
+
+---
+
+## Issue: Slow Download Speed
+
+**Pip takes forever to download packages**
+
+### Solutions:
+
+**Use faster mirror (if in China):**
+```bash
+pip install -i https://pypi.tuna.tsinghua.edu.cn/simple Django
+```
+
+**Increase timeout:**
+```bash
+pip install --timeout=1000 Django
+```
+
+**Use pip cache:**
+```bash
+pip install Django  # First time (slow)
+pip install Django  # Second time (fast, uses cache)
+```
+
+---
+
+## Issue: Hash Mismatch Error
+
+**Error:**
+```
+THESE PACKAGES DO NOT MATCH THE HASHES FROM THE REQUIREMENTS FILE
+```
+
+### Solutions:
+
+**Regenerate requirements.txt:**
+```bash
+pip freeze > requirements.txt
+```
+
+**Install without hash checking (temporary):**
+```bash
+pip install --no-deps -r requirements.txt
+```
+
+**Clear pip cache:**
+```bash
+pip cache purge
+```
+
+---
+
+## Issue: ImportError After Installing Package
+
+**Package installs but can't import**
+
+### Solutions:
+
+**Verify venv is activated:**
+```bash
+which python  # Should point to venv
+pip list      # Should show installed package
+```
+
+**Check package name vs import name:**
+```bash
+# Install name: django-cors-headers
+pip install django-cors-headers
+
+# Import name: corsheaders
+import corsheaders  # ← Different!
+```
+
+**Restart Python shell:**
+```bash
+exit()  # Exit Python shell
+python  # Start fresh
+import django  # Try again
+```
+
+---
+
+## Issue: Multiple pip Versions
+
+**`pip` points to wrong Python version**
+
+### Solution:
+
+**Always use `python -m pip`:**
+```bash
+# Instead of:
+pip install Django
+
+# Use:
+python -m pip install Django
+```
+
+**Or specify Python version:**
+```bash
+python3.13 -m pip install Django
+```
+
+---
+
+## Best Practices
+
+✅ **Always use virtual environments**
+```bash
+python3 -m venv venv
+source venv/bin/activate
+```
+
+✅ **Keep pip updated**
+```bash
+pip install --upgrade pip
+```
+
+✅ **Pin versions in production**
+```bash
+# requirements.txt
+Django==5.0.1
+djangorestframework==3.14.0
+```
+
+✅ **Use requirements.txt**
+```bash
+pip freeze > requirements.txt
+pip install -r requirements.txt
+```
+
+✅ **Don't mix conda and pip** (if using Anaconda)
+- Use conda for conda packages
+- Use pip only for packages not in conda
+
+---
+
+[← Back to django-project-setup](../SKILL.md)