gh-otoshek-claude-code-toolkit/skills/django-setup/troubleshooting/venv-issues.md

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