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

Troubleshooting: Virtual Environment Issues

← Back to main skill

---

Issue: ensurepip is not available

Full error:

Error: Command '[...]/python3', '-Im', 'ensurepip', '--upgrade', '--default-pip']' returned non-zero exit status 1

Solutions:

Ubuntu/Debian:

sudo apt install python3.13-venv python3.13-distutils -y

macOS (Homebrew):

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

Error:

venv\Scripts\Activate.ps1 cannot be loaded because running scripts is disabled on this system

Solution:

Allow scripts for current user:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Then retry activation:

venv\Scripts\Activate.ps1

Verify policy:

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:

source venv/bin/activate  # Correct
. venv/bin/activate       # Also works
bash venv/bin/activate    # Wrong - don't use bash

Windows - Use correct script:

# PowerShell
venv\Scripts\Activate.ps1

# Command Prompt
venv\Scripts\activate.bat

# Git Bash
source venv/Scripts/activate

Verify activation:

which python  # Should point to venv/bin/python
echo $VIRTUAL_ENV  # Should show venv path

---

Issue: Permission Denied on Activation

Error (macOS/Linux):

bash: venv/bin/activate: Permission denied

Solution:

Make script executable:

chmod +x venv/bin/activate
source venv/bin/activate

Or recreate venv:

rm -rf venv
python3 -m venv venv

---

Issue: venv Module Not Found

Error:

No module named venv

Solutions:

Ubuntu/Debian:

sudo apt install python3.13-venv -y

Fedora/RHEL:

sudo dnf install python3.13-venv -y

macOS:

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

(venv) $ python --version
Python 3.8.10  # But you wanted 3.13!

Solution:

Delete and recreate with specific version:

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:

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:

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:

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:

rm -rf ~/venv  # Or wherever it was created

Navigate to project first:

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:

python -m pip --version
python -m pip install <package>

Reinstall pip in venv:

curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
python get-pip.py
rm get-pip.py

Or recreate venv:

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:

pip cache purge

Remove unnecessary packages:

pip list  # See what's installed
pip uninstall <package>

Use --no-cache-dir when installing:

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:

deactivate

Close all terminals/IDEs using that folder

Windows - use PowerShell as Admin:

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

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

venv/
.venv/
env/
ENV/

✅ Document Python version in README

## Requirements
- Python 3.13+

✅ Use requirements.txt

pip freeze > requirements.txt
# Others can: pip install -r requirements.txt

---

← Back to django-project-setup