gh-otoshek-claude-code-toolkit/skills/django-setup/troubleshooting/pip-problems.md

# 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)