6.2 KiB
Troubleshooting: pip Problems
Issue: pip: command not found
After activating venv, pip doesn't work
Solutions:
Use python -m pip instead:
python -m pip --version
python -m pip install Django
python -m pip install --upgrade pip
Ensure venv is activated:
source venv/bin/activate # macOS/Linux
venv\Scripts\activate # Windows
Reinstall pip in venv:
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:
# 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:
/Applications/Python\ 3.13/Install\ Certificates.command
Or install certifi:
pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org certifi
Ubuntu/Debian:
sudo apt install ca-certificates
sudo update-ca-certificates
Temporary workaround (not recommended):
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:
python -m pip install --upgrade pip
If that fails:
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:
# Wrong
pip install django-rest-framework
# Correct
pip install djangorestframework
Check Python version compatibility:
python --version # Some packages require Python 3.11+
Try older package version:
pip install "Django<5.0" # Install Django 4.x
Update pip and setuptools:
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+):
pip install --upgrade <package>
Install specific compatible versions:
pip install package-a package-b==2.0
Use pip-tools for dependency management:
pip install pip-tools
# Create requirements.in with your deps
pip-compile requirements.in
pip-sync requirements.txt
Nuclear option - recreate venv:
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:
xcode-select --install
brew install openssl
Ubuntu/Debian:
sudo apt install python3-dev build-essential libssl-dev libffi-dev -y
Fedora/RHEL:
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:
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):
python3 -m venv venv
source venv/bin/activate
pip install Django
Or use --break-system-packages (not recommended):
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):
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple Django
Increase timeout:
pip install --timeout=1000 Django
Use pip cache:
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:
pip freeze > requirements.txt
Install without hash checking (temporary):
pip install --no-deps -r requirements.txt
Clear pip cache:
pip cache purge
Issue: ImportError After Installing Package
Package installs but can't import
Solutions:
Verify venv is activated:
which python # Should point to venv
pip list # Should show installed package
Check package name vs import name:
# Install name: django-cors-headers
pip install django-cors-headers
# Import name: corsheaders
import corsheaders # ← Different!
Restart Python shell:
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:
# Instead of:
pip install Django
# Use:
python -m pip install Django
Or specify Python version:
python3.13 -m pip install Django
Best Practices
✅ Always use virtual environments
python3 -m venv venv
source venv/bin/activate
✅ Keep pip updated
pip install --upgrade pip
✅ Pin versions in production
# requirements.txt
Django==5.0.1
djangorestframework==3.14.0
✅ Use requirements.txt
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