Python venv activeert niet? 5 fixes die echt werken (backend)

Een Python virtual environment (venv) hoort “gewoon” te activeren, maar in de praktijk gaat het vaak mis: je prompt verandert niet, python blijft naar je systeeminstallatie wijzen, pip installeert in de verkeerde site-packages, of je krijgt permissie- en policy-errors. In backend-projecten is dit extra pijnlijk: je draait een API, Celery worker, migrations, tests, en ineens blijken dependencies “verdwenen” of in conflict.

In deze tutorial krijg je 5 fixes die echt werken, inclusief diepe uitleg over wat er onder de motorkap gebeurt, en concrete commando’s voor Windows, macOS en Linux. Je leert ook hoe je verifieert dat je venv écht actief is, en hoe je voorkomt dat het opnieuw misgaat.

Inhoud

1. Wat “activatie” eigenlijk doet (en wat niet)
2. Symptomen: hoe herken je dat je venv niet actief is?
3. Fix 1 — Gebruik het juiste activatie-script (per shell/OS)
4. Fix 2 — Omzeil activatie: gebruik altijd het venv-pad naar python/pip
5. Fix 3 — Windows Execution Policy / scripts geblokkeerd
6. Fix 4 — Verkeerde Python/venv door PATH, aliases, pyenv, conda of IDE
7. Fix 5 — Venv is corrupt of verkeerd aangemaakt: rebuild correct
8. Checklist: venv correct? (snelle verificatie)
9. Backend best practices om venv-problemen te voorkomen

Wat “activatie” eigenlijk doet (en wat niet)

Een venv is in essentie een mapstructuur met:

• een Python executable (of een shim/symlink) in venv/bin/ (macOS/Linux) of venv\Scripts\ (Windows)
• een eigen site-packages directory waar pip packages installeert
• metadata zoals pyvenv.cfg die vertelt welke “base” Python gebruikt wordt

Activatie is géén magische modus in Python. Het is simpelweg een shell-script dat:

1. Je PATH aanpast zodat python en pip eerst uit de venv komen.
2. Variabelen zet zoals VIRTUAL_ENV.
3. Soms je prompt aanpast (bijv. (venv)).

Daarom kunnen dingen misgaan als:

• je het verkeerde activatie-script gebruikt voor jouw shell,
• je shell scripts niet mag uitvoeren (Windows policy),
• je PATH/alias een andere python blijft pakken,
• je in een IDE een andere interpreter gebruikt dan in je terminal.

Belangrijk: je kunt altijd zonder activatie werken door direct het venv-pad te gebruiken (zie Fix 2). Activatie is vooral gemak.

Symptomen: hoe herken je dat je venv niet actief is?

Typische signalen:

• Je prompt toont geen (venv) (niet altijd doorslaggevend, maar vaak een hint).
• which python (macOS/Linux) of where python (Windows) wijst naar een systeemlocatie.
• python -m pip install ... installeert packages “ergens anders”.
• pip list toont niet de packages die je verwacht.
• Je backend app faalt met ModuleNotFoundError terwijl je “zeker weet” dat je het geïnstalleerd hebt.

Snelle diagnose-commando’s

macOS/Linux:

which python
which pip
python -c "import sys; print(sys.executable); print(sys.prefix)"
python -m pip -V
echo $VIRTUAL_ENV

Windows (PowerShell):

where python
where pip
python -c "import sys; print(sys.executable); print(sys.prefix)"
python -m pip -V
echo $env:VIRTUAL_ENV

Interpretatie:

• sys.executable moet naar jouw venv wijzen, bv. .../project/.venv/bin/python of ...\project\.venv\Scripts\python.exe.
• python -m pip -V moet een pad tonen binnen dezelfde venv.

Fix 1 — Gebruik het juiste activatie-script (per shell/OS)

De meest voorkomende oorzaak: je gebruikt het verkeerde commando voor jouw shell. Er zijn meerdere scripts omdat Bash, Zsh, Fish, PowerShell en cmd andere syntaxis hebben.

1.1 Maak een venv aan (als je die nog niet hebt)

Ga naar je projectmap:

cd /pad/naar/jouw/backend-project

Maak venv (aanbevolen naam: .venv):

python -m venv .venv

Als python niet de juiste versie is, gebruik dan expliciet python3:

python3 -m venv .venv

Backend tip: .venv in de projectroot is handig voor IDE-detectie en tooling.

1.2 Activeer correct per platform

macOS/Linux (Bash/Zsh)

source .venv/bin/activate

Als je “permission denied” krijgt, is dat meestal niet het activatie-script zelf, maar je shell of filesystem. Check dan Fix 5 (rebuild) of Fix 4 (shell/alias).

Fish shell

source .venv/bin/activate.fish

Windows — PowerShell

.\.venv\Scripts\Activate.ps1

Windows — Command Prompt (cmd.exe)

.\.venv\Scripts\activate.bat

1.3 Veelgemaakte fouten

• source venv/bin/activate terwijl je venv .venv heet.
• PowerShell-commando in cmd gebruiken of andersom.
• Vergeten dat je in een andere map zit dan je denkt.

Controleer je huidige map:

macOS/Linux

pwd
ls -la

Windows

Get-Location
dir

Fix 2 — Omzeil activatie: gebruik altijd het venv-pad naar python/pip

Soms wil je activatie vermijden (bijv. in CI, Docker, Makefiles, scripts, of als policies roet in het eten gooien). Dit is ook de meest “waterdichte” methode: je gebruikt direct de interpreter uit de venv.

2.1 Gebruik python -m pip (belangrijk)

Gebruik bij voorkeur:

python -m pip install -r requirements.txt

Waarom? Omdat pip als los commando soms naar een andere Python wijst. python -m pip garandeert: pip draait binnen déze Python.

2.2 Directe paden

macOS/Linux:

./.venv/bin/python -m pip install -r requirements.txt
./.venv/bin/python -m pytest
./.venv/bin/python -m uvicorn app.main:app --reload

Windows (PowerShell):

.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\.venv\Scripts\python.exe -m pytest
.\.venv\Scripts\python.exe -m uvicorn app.main:app --reload

2.3 Waarom dit werkt (dieper)

Activatie wijzigt alleen je shell-omgeving (PATH). Als je per ongeluk een subshell, een task runner, of een IDE-run-config gebruikt die niet dezelfde omgeving erft, kan je activatie “verdwijnen”. Door het pad naar python te hardcoden, omzeil je PATH volledig.

Voor backend tooling is dit ideaal in:

• Makefile targets
• package.json scripts (voor fullstack repo’s)
• CI pipelines (GitHub Actions/GitLab CI)
• pre-commit hooks

Voorbeeld Makefile:

PY=./.venv/bin/python

install:
	$(PY) -m pip install -r requirements.txt

run:
	$(PY) -m uvicorn app.main:app --reload

Fix 3 — Windows Execution Policy / scripts geblokkeerd

Op Windows is dit dé klassieker: PowerShell blokkeert scripts, waardoor Activate.ps1 niet mag draaien.

3.1 Symptoom

Je ziet iets als:

• “running scripts is disabled on this system”
• “cannot be loaded because running scripts is disabled”

3.2 Oplossing: policy aanpassen (veilig en gericht)

Open PowerShell als jouw gebruiker (meestal géén admin nodig) en zet policy voor CurrentUser:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Controleer:

Get-ExecutionPolicy -List

Daarna activeer opnieuw:

.\.venv\Scripts\Activate.ps1

Wat betekent RemoteSigned?

• Lokale scripts mogen draaien.
• Scripts gedownload van internet moeten “gesigned” zijn (of je moet ze unblocken).
• Dit is een gangbare balans tussen veiligheid en bruikbaarheid.

3.3 Alternatief: unblock het activatie-script

Als je venv-map is gekopieerd of gedownload, kan Windows het markeren als “from the internet”. Dan kun je unblocken:

Unblock-File .\.venv\Scripts\Activate.ps1

3.4 Alternatief: gebruik cmd activatie of Fix 2

Als je policy niet mag aanpassen (bedrijfslaptop):

• Gebruik cmd.exe:

  .\.venv\Scripts\activate.bat

• Of gebruik Fix 2 (directe python.exe paden), wat vaak het meest robuust is.

Fix 4 — Verkeerde Python/venv door PATH, aliases, pyenv, conda of IDE

Soms “activeer” je correct, maar toch blijft python naar iets anders wijzen. Dit komt door:

• alias python=python3 of alias naar een specifieke binary
• pyenv shims
• conda base environment dat automatisch activeert
• IDE (VS Code/PyCharm) gebruikt een andere interpreter dan je terminal
• meerdere Pythons geïnstalleerd (Microsoft Store Python, system Python, Homebrew Python)

4.1 Check wat je shell écht uitvoert

macOS/Linux:

type -a python
type -a pip
which -a python

Windows PowerShell:

Get-Command python
Get-Command pip

Als je na activatie nog steeds een pad ziet buiten .venv, dan overschrijft iets je PATH-resolutie.

4.2 Conda “base” auto-activatie uitzetten (indien relevant)

Als je conda gebruikt en je ziet steeds (base):

conda config --set auto_activate_base false

Herstart je terminal.

4.3 pyenv: zorg dat je venv met de juiste Python is gemaakt

Als je pyenv gebruikt, kies eerst je Python:

pyenv versions
pyenv local 3.12.2
python -V
python -m venv .venv

Belangrijk: een venv “onthoudt” de base interpreter via pyvenv.cfg. Als je later van Python wisselt, kan de venv inconsistent worden (zie Fix 5).

4.4 VS Code: interpreter expliciet kiezen

In VS Code kan je terminal wél geactiveerd zijn, maar de Run/Debug gebruikt een andere interpreter.

• Open Command Palette → Python: Select Interpreter
• Kies de interpreter in .venv (bijv. .venv/bin/python)

Controleer in VS Code terminal:

python -c "import sys; print(sys.executable)"

En in je app-run (bijv. debug console) idem.

4.5 pip vs python -m pip (nogmaals, omdat dit vaak de echte bug is)

Als pip install “werkt” maar je app vindt het package niet, dan installeer je waarschijnlijk in een andere Python.

Gebruik altijd:

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

En check dat pip -V hetzelfde prefix toont als sys.executable.

Fix 5 — Venv is corrupt of verkeerd aangemaakt: rebuild correct

Soms is de venv simpelweg niet gezond meer. Oorzaken:

• Je hebt de venv-map gekopieerd tussen machines/OS’en (niet portable).
• Je hebt Python geüpdatet (bijv. 3.11 → 3.12) en de venv wijst nog naar oude libs.
• Je projectpad is verplaatst en symlinks zijn gebroken.
• Je disk/permissions hebben issues.

De snelste betrouwbare oplossing: verwijder en maak opnieuw.

5.1 Verwijder de venv

macOS/Linux:

rm -rf .venv

Windows (PowerShell):

Remove-Item -Recurse -Force .\.venv

5.2 Maak opnieuw aan met de juiste Python

Controleer eerst je Python:

python -V
python -c "import sys; print(sys.executable)"

Maak venv:

python -m venv .venv

Activeer (optioneel):

source .venv/bin/activate
# of op Windows:
# .\.venv\Scripts\Activate.ps1

5.3 Upgrade pip/setuptools/wheel (aanbevolen)

Binnen de venv:

python -m pip install --upgrade pip setuptools wheel

5.4 Installeer dependencies opnieuw

Als je requirements.txt gebruikt:

python -m pip install -r requirements.txt

Als je pyproject.toml gebruikt (bijv. met Poetry of uv), gebruik de bijbehorende tool. Voor een “pure pip” aanpak met PEP 517 builds:

python -m pip install .

Of editable (handig voor backend development):

python -m pip install -e .

5.5 Waarom rebuild vaak beter is dan debuggen

Een venv is goedkoop om opnieuw te maken. Debuggen van half-broken symlinks of oude compiled wheels kost vaak meer tijd dan:

1. venv weggooien
2. opnieuw aanmaken
3. dependencies opnieuw installeren

Voor backend teams is dit ook het meest reproduceerbaar.

Checklist: venv correct? (snelle verificatie)

Gebruik deze checklist nadat je denkt dat alles werkt.

1) Staat VIRTUAL_ENV goed?

macOS/Linux:

echo $VIRTUAL_ENV

Windows:

echo $env:VIRTUAL_ENV

Moet wijzen naar jouw .venv pad.

2) Wijst python naar .venv?

macOS/Linux:

which python
python -c "import sys; print(sys.executable)"

Windows:

where python
python -c "import sys; print(sys.executable)"

3) Wijst pip naar dezelfde omgeving?

python -m pip -V

Je ziet iets als:

• .../.venv/lib/python3.x/site-packages/pip ... (macOS/Linux)
• ...\ .venv\Lib\site-packages\pip ... (Windows)

4) Test een import die je nodig hebt (backend)

Bijv. FastAPI:

python -c "import fastapi; import uvicorn; print('ok')"

Of Django:

python -c "import django; print(django.get_version())"

5) Draai je server met de venv-python

FastAPI/uvicorn:

python -m uvicorn app.main:app --reload --port 8000

Django:

python manage.py runserver

Backend best practices om venv-problemen te voorkomen

1) Gebruik altijd .venv in de projectroot

Veel tools herkennen dit automatisch (VS Code, pyright, ruff, etc.). Dit vermindert “verkeerde interpreter” problemen.

Aanbevolen structuur:

backend-project/
  app/
  tests/
  pyproject.toml of requirements.txt
  .venv/

2) Gebruik python -m pip als standaard

Maak er een gewoonte van. Het voorkomt 80% van “pip installeert verkeerd” issues.

Slecht:

pip install -r requirements.txt

Goed:

python -m pip install -r requirements.txt

3) Pin je dependencies en Python-versie

• Gebruik requirements.txt met pinned versies (of constraints).
• Leg je Python-versie vast met:
  • .python-version (pyenv)
  • of documenteer in README
  • of gebruik tooling zoals uv/Poetry

Voorbeeld in README:

python -V  # verwacht 3.12.x

4) Automatiseer setup

Een Makefile of justfile voorkomt dat iedereen andere commando’s gebruikt.

Voorbeeld Makefile (cross-platform is lastiger, maar op Unix prima):

VENV=.venv
PY=$(VENV)/bin/python

venv:
	python3 -m venv $(VENV)
	$(PY) -m pip install --upgrade pip setuptools wheel

install:
	$(PY) -m pip install -r requirements.txt

run:
	$(PY) -m uvicorn app.main:app --reload

5) Gebruik in CI altijd expliciete paden (Fix 2)

In CI wil je geen afhankelijkheid van shell-activatie. Gebruik:

python -m venv .venv
./.venv/bin/python -m pip install -r requirements.txt
./.venv/bin/python -m pytest

Samenvatting: de 5 fixes in één oogopslag

1. Juiste activatie-script per shell/OS

   • source .venv/bin/activate (Bash/Zsh)
   • .\.venv\Scripts\Activate.ps1 (PowerShell)

2. Omzeil activatie en gebruik direct ./.venv/bin/python of .\.venv\Scripts\python.exe + -m pip.

3. Windows Execution Policy fixen met Set-ExecutionPolicy RemoteSigned -Scope CurrentUser of Unblock-File.

4. PATH/alias/conda/pyenv/IDE conflicts opsporen met type -a python, Get-Command python, en interpreter expliciet kiezen.

5. Rebuild venv als hij corrupt/verplaatst/verouderd is: .venv verwijderen, opnieuw python -m venv .venv, dependencies opnieuw installeren.

Als je jouw OS + shell (bijv. “Windows 11 PowerShell”, “macOS zsh”, “Ubuntu bash”) en de exacte foutmelding plakt, kan ik de juiste fix aanwijzen en je commando’s exact op jouw situatie afstemmen.