Initial commit
This commit is contained in:
Zhongwei Li
480
skills/django-setup/troubleshooting/django-errors.md
Normal file
480
skills/django-setup/troubleshooting/django-errors.md
Normal file
@@ -0,0 +1,480 @@
|
||||
# Troubleshooting: Django Errors
|
||||
|
||||
[← Back to main skill](../SKILL.md)
|
||||
|
||||
---
|
||||
|
||||
## Issue: `django-admin: command not found` {#django-admin}
|
||||
|
||||
**After installing Django, command doesn't work**
|
||||
|
||||
### Solutions:
|
||||
|
||||
**Ensure venv is activated:**
|
||||
```bash
|
||||
source venv/bin/activate # macOS/Linux
|
||||
venv\Scripts\activate # Windows
|
||||
```
|
||||
|
||||
**Use `python -m django` instead:**
|
||||
```bash
|
||||
python -m django --version
|
||||
python -m django startproject myproject
|
||||
```
|
||||
|
||||
**Check Django is installed:**
|
||||
```bash
|
||||
pip list | grep Django
|
||||
# or
|
||||
pip show Django
|
||||
```
|
||||
|
||||
**Reinstall Django:**
|
||||
```bash
|
||||
pip install --force-reinstall Django
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Issue: Port 8000 Already in Use {#port-in-use}
|
||||
|
||||
**Error:**
|
||||
```
|
||||
Error: That port is already in use.
|
||||
```
|
||||
|
||||
### Solutions:
|
||||
|
||||
**Use different port:**
|
||||
```bash
|
||||
python manage.py runserver 8001
|
||||
python manage.py runserver 0.0.0.0:8080
|
||||
```
|
||||
|
||||
**Kill process using port 8000:**
|
||||
|
||||
**macOS/Linux:**
|
||||
```bash
|
||||
lsof -ti:8000 | xargs kill -9
|
||||
```
|
||||
|
||||
**Windows (PowerShell):**
|
||||
```powershell
|
||||
netstat -ano | findstr :8000
|
||||
# Note the PID, then:
|
||||
taskkill /PID <pid> /F
|
||||
```
|
||||
|
||||
**Windows (Command Prompt):**
|
||||
```cmd
|
||||
FOR /F "tokens=5" %P IN ('netstat -ano ^| findstr :8000') DO TaskKill /PID %P /F
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Issue: `ModuleNotFoundError: No module named 'django'`
|
||||
|
||||
**Django installed but Python can't find it**
|
||||
|
||||
### Solutions:
|
||||
|
||||
**Verify venv is activated:**
|
||||
```bash
|
||||
which python # Should point to venv/bin/python
|
||||
echo $VIRTUAL_ENV # Should show venv path
|
||||
```
|
||||
|
||||
**Check Django installation:**
|
||||
```bash
|
||||
pip list
|
||||
pip show Django
|
||||
```
|
||||
|
||||
**Install Django in venv:**
|
||||
```bash
|
||||
source venv/bin/activate
|
||||
pip install Django
|
||||
```
|
||||
|
||||
**Check you're using venv Python:**
|
||||
```bash
|
||||
python --version
|
||||
which python
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Issue: `django.core.exceptions.ImproperlyConfigured`
|
||||
|
||||
**Common misconfigurations**
|
||||
|
||||
### `SECRET_KEY` not set
|
||||
|
||||
**Error:**
|
||||
```
|
||||
ImproperlyConfigured: The SECRET_KEY setting must not be empty.
|
||||
```
|
||||
|
||||
**Solution:**
|
||||
- Don't delete SECRET_KEY from settings.py
|
||||
- If using environment variables, ensure .env file exists
|
||||
|
||||
### Database configuration error
|
||||
|
||||
**Error:**
|
||||
```
|
||||
ImproperlyConfigured: settings.DATABASES is improperly configured
|
||||
```
|
||||
|
||||
**Solution - Check database settings:**
|
||||
```python
|
||||
# settings.py
|
||||
DATABASES = {
|
||||
'default': {
|
||||
'ENGINE': 'django.db.backends.sqlite3',
|
||||
'NAME': BASE_DIR / 'db.sqlite3',
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Issue: Migrations Not Applying
|
||||
|
||||
**Error:**
|
||||
```
|
||||
django.db.utils.OperationalError: no such table
|
||||
```
|
||||
|
||||
### Solutions:
|
||||
|
||||
**Run migrations:**
|
||||
```bash
|
||||
python manage.py migrate
|
||||
```
|
||||
|
||||
**Check migration files exist:**
|
||||
```bash
|
||||
ls */migrations/
|
||||
# Should see 0001_initial.py files
|
||||
```
|
||||
|
||||
**Reset database (development only!):**
|
||||
```bash
|
||||
rm db.sqlite3
|
||||
python manage.py migrate
|
||||
```
|
||||
|
||||
**Make migrations if they don't exist:**
|
||||
```bash
|
||||
python manage.py makemigrations
|
||||
python manage.py migrate
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Issue: Static Files Not Loading
|
||||
|
||||
**CSS/JS files show 404 in browser**
|
||||
|
||||
### Solutions:
|
||||
|
||||
**Run collectstatic:**
|
||||
```bash
|
||||
python manage.py collectstatic
|
||||
```
|
||||
|
||||
**Check STATIC_URL in settings.py:**
|
||||
```python
|
||||
STATIC_URL = '/static/'
|
||||
```
|
||||
|
||||
**For development, ensure DEBUG=True:**
|
||||
```python
|
||||
DEBUG = True
|
||||
```
|
||||
|
||||
**Check INSTALLED_APPS includes:**
|
||||
```python
|
||||
INSTALLED_APPS = [
|
||||
...
|
||||
'django.contrib.staticfiles',
|
||||
]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Issue: Template Not Found
|
||||
|
||||
**Error:**
|
||||
```
|
||||
TemplateDoesNotExist at /path/
|
||||
```
|
||||
|
||||
### Solutions:
|
||||
|
||||
**Check template path:**
|
||||
```python
|
||||
# settings.py
|
||||
TEMPLATES = [
|
||||
{
|
||||
'DIRS': [BASE_DIR / 'templates'], # Add this
|
||||
...
|
||||
},
|
||||
]
|
||||
```
|
||||
|
||||
**Create templates directory:**
|
||||
```bash
|
||||
mkdir -p templates
|
||||
```
|
||||
|
||||
**Check template name matches:**
|
||||
```python
|
||||
# views.py
|
||||
return render(request, 'index.html') # Must match file name exactly
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Issue: ALLOWED_HOSTS Error in Production
|
||||
|
||||
**Error:**
|
||||
```
|
||||
Invalid HTTP_HOST header: 'yourdomain.com'. You may need to add 'yourdomain.com' to ALLOWED_HOSTS.
|
||||
```
|
||||
|
||||
### Solution:
|
||||
|
||||
**Add domain to ALLOWED_HOSTS:**
|
||||
```python
|
||||
# settings.py
|
||||
DEBUG = False # In production
|
||||
ALLOWED_HOSTS = ['yourdomain.com', 'www.yourdomain.com']
|
||||
```
|
||||
|
||||
**For development:**
|
||||
```python
|
||||
DEBUG = True
|
||||
ALLOWED_HOSTS = [] # Empty list allows localhost automatically
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Issue: CSRF Verification Failed
|
||||
|
||||
**Error:**
|
||||
```
|
||||
Forbidden (403)
|
||||
CSRF verification failed. Request aborted.
|
||||
```
|
||||
|
||||
### Solutions:
|
||||
|
||||
**Ensure CSRF middleware is enabled:**
|
||||
```python
|
||||
# settings.py
|
||||
MIDDLEWARE = [
|
||||
...
|
||||
'django.middleware.csrf.CsrfViewMiddleware',
|
||||
...
|
||||
]
|
||||
```
|
||||
|
||||
**Include CSRF token in forms:**
|
||||
```html
|
||||
<form method="post">
|
||||
{% csrf_token %}
|
||||
...
|
||||
</form>
|
||||
```
|
||||
|
||||
**For AJAX, include CSRF token in headers:**
|
||||
```javascript
|
||||
// Get CSRF token from cookie
|
||||
const csrftoken = document.querySelector('[name=csrfmiddlewaretoken]').value;
|
||||
|
||||
fetch('/api/endpoint/', {
|
||||
method: 'POST',
|
||||
headers: {
|
||||
'X-CSRFToken': csrftoken
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Issue: Admin Interface Not Working
|
||||
|
||||
**Can't access /admin/**
|
||||
|
||||
### Solutions:
|
||||
|
||||
**Run migrations:**
|
||||
```bash
|
||||
python manage.py migrate
|
||||
```
|
||||
|
||||
**Create superuser:**
|
||||
```bash
|
||||
python manage.py createsuperuser
|
||||
```
|
||||
|
||||
**Check URL configuration:**
|
||||
```python
|
||||
# urls.py
|
||||
from django.contrib import admin
|
||||
|
||||
urlpatterns = [
|
||||
path('admin/', admin.site.urls),
|
||||
]
|
||||
```
|
||||
|
||||
**Ensure admin app is installed:**
|
||||
```python
|
||||
# settings.py
|
||||
INSTALLED_APPS = [
|
||||
'django.contrib.admin',
|
||||
'django.contrib.auth',
|
||||
'django.contrib.contenttypes',
|
||||
'django.contrib.sessions',
|
||||
'django.contrib.messages',
|
||||
]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Issue: Project Won't Start After Renaming
|
||||
|
||||
**Renamed project but errors occur**
|
||||
|
||||
### Solution:
|
||||
|
||||
**Update references in these files:**
|
||||
|
||||
**manage.py:**
|
||||
```python
|
||||
os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'new_name.settings')
|
||||
```
|
||||
|
||||
**asgi.py:**
|
||||
```python
|
||||
os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'new_name.settings')
|
||||
```
|
||||
|
||||
**wsgi.py:**
|
||||
```python
|
||||
os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'new_name.settings')
|
||||
```
|
||||
|
||||
**Rename project directory itself**
|
||||
|
||||
---
|
||||
|
||||
## Issue: Circular Import Errors
|
||||
|
||||
**Error:**
|
||||
```
|
||||
ImportError: cannot import name 'X' from partially initialized module 'Y'
|
||||
```
|
||||
|
||||
### Solutions:
|
||||
|
||||
**Avoid circular imports:**
|
||||
```python
|
||||
# ❌ Bad - circular import
|
||||
# models.py
|
||||
from .views import something
|
||||
|
||||
# views.py
|
||||
from .models import Model
|
||||
```
|
||||
|
||||
**Use lazy imports:**
|
||||
```python
|
||||
# ✅ Good - import inside function
|
||||
def my_view(request):
|
||||
from .models import Model # Import here
|
||||
...
|
||||
```
|
||||
|
||||
**Or use Django's get_model:**
|
||||
```python
|
||||
from django.apps import apps
|
||||
Model = apps.get_model('app_name', 'ModelName')
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Issue: `SyntaxError` in settings.py
|
||||
|
||||
**Error:**
|
||||
```
|
||||
SyntaxError: invalid syntax
|
||||
```
|
||||
|
||||
### Solutions:
|
||||
|
||||
**Check Python version:**
|
||||
```bash
|
||||
python --version # Should be 3.8+
|
||||
```
|
||||
|
||||
**Look for common syntax errors:**
|
||||
```python
|
||||
# ❌ Missing comma
|
||||
INSTALLED_APPS = [
|
||||
'django.contrib.admin' # Missing comma!
|
||||
'django.contrib.auth',
|
||||
]
|
||||
|
||||
# ✅ Correct
|
||||
INSTALLED_APPS = [
|
||||
'django.contrib.admin', # Comma here
|
||||
'django.contrib.auth',
|
||||
]
|
||||
```
|
||||
|
||||
**Validate Python syntax:**
|
||||
```bash
|
||||
python -m py_compile backend/settings.py
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Diagnostic Commands
|
||||
|
||||
**Check Django installation:**
|
||||
```bash
|
||||
python -m django --version
|
||||
```
|
||||
|
||||
**Check Python version:**
|
||||
```bash
|
||||
python --version
|
||||
```
|
||||
|
||||
**Run system checks:**
|
||||
```bash
|
||||
python manage.py check
|
||||
python manage.py check --deploy
|
||||
```
|
||||
|
||||
**List installed packages:**
|
||||
```bash
|
||||
pip list
|
||||
```
|
||||
|
||||
**Check migrations status:**
|
||||
```bash
|
||||
python manage.py showmigrations
|
||||
```
|
||||
|
||||
**Test database connection:**
|
||||
```bash
|
||||
python manage.py dbshell
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
[← Back to django-project-setup](../SKILL.md)
|
||||
386
skills/django-setup/troubleshooting/pip-problems.md
Normal file
386
skills/django-setup/troubleshooting/pip-problems.md
Normal file
@@ -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)
|
||||
376
skills/django-setup/troubleshooting/venv-issues.md
Normal file
376
skills/django-setup/troubleshooting/venv-issues.md
Normal file
@@ -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)
|
||||
Reference in New Issue
Block a user