Virtuele omgevingen (venv)

Stel je voor: je gaat op kamp en je moet je rugzak pakken. Voor een sportkamp stop je er andere dingen in dan voor een muziekkamp. Als je alles door elkaar gooit, vind je nooit iets terug.

Zo werkt het ook met Python-projecten. Elk project heeft zijn eigen “rugzak” nodig: een virtuele omgeving met precies de juiste spullen erin.

Wat is een virtuele omgeving?

Een virtuele omgeving (kortweg venv, spreek uit: “ven-vee”) is een aparte map op je computer waar Python én alle extra pakketten voor één project in zitten.

Stel dat je twee projecten hebt:

• Project A gebruikt Pygame versie 2.5
• Project B gebruikt Pygame versie 2.6

Zonder virtuele omgevingen zou je maar één versie van Pygame op je computer kunnen installeren. Het ene project zou dan niet meer werken. Met virtuele omgevingen heeft elk project zijn eigen afgesloten doos met de juiste versie erin. Ze staan elkaar niet in de weg.

Metafoor: Een virtuele omgeving is als een eigen rugzak per project. Je stopt er precies in wat dat project nodig heeft, en de rugzakken staan los van elkaar in de kast.

Waarom gebruiken we ze?

1. Geen ruzie tussen projecten. Versie 2.5 en 2.6 kunnen allebei bestaan, elk in hun eigen omgeving.
2. Delen is makkelijk. Als jij je project deelt met een vriend(in), hoef je niet alle pakketten mee te sturen. Je vriend(in) maakt gewoon een eigen virtuele omgeving en installeert dezelfde pakketten.
3. Je computer blijft opgeruimd. Je installeert niets “zomaar” op je hele computer. Alles blijft netjes in de rugzak van het juiste project.

Hoe maak je een virtuele omgeving met uv

uv is de Python-pakketbeheerder die we op CoderDojo gebruiken. Hij kan virtuele omgevingen maken én beheren.

Stap 1: Open een terminal

• Windows: Druk op ⊞ Windows, typ cmd en open “Command Prompt” (of gebruik PowerShell).
• macOS / Linux: Open “Terminal”.

Stap 2: Ga naar de map van je project

cd pad/naar/jouw/projectmap

Stap 3: Maak de virtuele omgeving aan

uv venv

uv maakt nu een mapje .venv aan in je projectmap. Daarin zit een aparte Python-installatie.

Wil je een specifieke Python-versie gebruiken? Dat kan ook:

uv venv --python 3.13

Waarom zou je dat doen? Omdat Pygame en Pgzero nog niet werken met Python 3.14 of hoger. Door --python 3.13 te gebruiken, ben je zeker dat alles werkt.

Stap 4: Activeer de virtuele omgeving

De omgeving bestaat, maar je moet hem nog “aanzetten”. Dat noemen we activeren.

Windows (Command Prompt of PowerShell):

.venv\Scripts\activate

macOS / Linux:

source .venv/bin/activate

Na activeren zie je links in je terminal (.venv) verschijnen. Dat is het teken dat je nú in je virtuele omgeving werkt.

(.venv) seppe@computer:~/project$

Stap 5: Installeer pakketten

Nu je omgeving actief is, kun je pakketten installeren. Ze komen alleen in deze ene rugzak terecht:

uv add pgzero pygame

Stap 6: Uitschakelen (deactiveren)

Klaar met programmeren? Typ gewoon:

deactivate

Het (.venv)-teken verdwijnt en je werkt weer met de gewone Python van je computer.

Waar moet je op letten?

⚠️ Vergeet de omgeving niet te activeren

De meest gemaakte fout: je opent een nieuwe terminal en vergeet de virtuele omgeving te activeren. Python klaagt dan dat het pakketten niet vindt, ook al heb je ze wél geïnstalleerd.

Oplossing: activeer altijd eerst met .venv\Scripts\activate (Windows) of source .venv/bin/activate (macOS/Linux) voor je je programma start.

⚠️ Zet .venv in .gitignore

De map .venv is groot (soms honderden MB’s). Die moet je niet delen via Git of GitHub. Zet .venv in je .gitignore-bestand, zodat Git hem overslaat:

.venv/

Jouw vriend(in) maakt gewoon een eigen .venv aan met uv venv en installeert dezelfde pakketten via het pyproject.toml-bestand dat wél in Git zit.

⚠️ Gebruik uv run als shortcut

Geen zin om telkens te activeren en deactiveren? uv heeft een handige snelkoppeling:

uv run python main.py

Dit voert python main.py uit binnen de virtuele omgeving, ook al is die niet geactiveerd. uv snapt zelf welke omgeving bij het project hoort.

⚠️ Verschillende terminals, verschillende omgevingen

Activeer je de omgeving in de ene terminal, dan is hij niet automatisch actief in een andere terminal. Je moet elke terminal apart activeren waar je de omgeving wil gebruiken.

Samengevat

De gulden regel: zie je (.venv) in je terminal? Dan zit je goed. Zie je het niet? Activeer eerst, programmeer daarna.

Wat is het verschil met virtualenv en pip? Voor uv bestonden er al andere tools zoals virtualenv (voor omgevingen) en pip (voor pakketten). Daarmee kon je hetzelfde doen, maar je moest twee aparte commando’s gebruiken en het werkte een stuk trager. uv doet alles in één keer, is veel sneller, en is een stuk makkelijker voor beginners. Op CoderDojo gebruiken we daarom het liefst uv.

Heb je problemen met je virtuele omgeving? Kijk bij Problemen oplossen voor veelvoorkomende fouten.