Virtual environments (venv)

Imagine: you’re going on camp and you have to pack your backpack. For a sports camp you put different things in it than for a music camp. If you throw everything together, you never find anything back.

That’s how it works with Python projects too. Every project needs its own “backpack”: a virtual environment with exactly the right stuff in it.

What is a virtual environment?

A virtual environment (short: venv, pronounced “ven-vee”) is a separate folder on your computer that holds Python and all the extra packages for one project.

Say you have two projects:

• Project A uses Pygame version 2.5
• Project B uses Pygame version 2.6

Without virtual environments you could only install one version of Pygame on your computer. One of the projects would then stop working. With virtual environments every project has its own sealed box with the right version in it. They don’t get in each other’s way.

Metaphor: A virtual environment is like an own backpack per project. You put in exactly what that project needs, and the backpacks stand apart from each other in the cupboard.

Why do we use them?

1. No fighting between projects. Version 2.5 and 2.6 can both exist, each in its own environment.
2. Sharing is easy. If you share your project with a friend, you don’t have to send all the packages along. Your friend just creates their own virtual environment and installs the same packages.
3. Your computer stays tidy. You don’t install anything “just like that” on your whole computer. Everything stays neatly in the backpack of the right project.

How do you make a virtual environment with uv

uv is the Python package manager we use at CoderDojo. It can create and manage virtual environments.

Step 1: Open a terminal

• Windows: Press ⊞ Windows, type cmd and open “Command Prompt” (or use PowerShell).
• macOS / Linux: Open “Terminal”.

Step 2: Go to your project folder

cd pad/naar/jouw/projectmap

Step 3: Create the virtual environment

uv venv

uv now creates a .venv folder in your project folder. It holds a separate Python installation.

Want to use a specific Python version? That works too:

uv venv --python 3.14

Why would you do that? That way you’re sure you use a Python version that works with our game libraries. Choose 3.13, 3.14 or 3.15.

Step 4: Activate the virtual environment

The environment exists, but you still have to “switch it on”. We call that activating.

Windows (Command Prompt or PowerShell):

.venv\Scripts\activate

macOS / Linux:

source .venv/bin/activate

After activating you see (.venv) appear on the left in your terminal. That is the sign that you are now working inside your virtual environment.

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

Step 5: Install packages

Now that your environment is active, you can install packages. They end up only in this one backpack:

uv add pgzero pygame-ce

So also put this line in your pyproject.toml:

[tool.uv]
exclude-dependencies = ["pygame"]

Step 6: Turning it off (deactivating)

Done programming? Just type:

deactivate

The (.venv) sign disappears and you work with the normal Python of your computer again.

What do you need to watch out for?

⚠️ Don’t forget to activate the environment

The most common mistake: you open a new terminal and forget to activate the virtual environment. Python then complains that it can’t find the packages, even though you did install them.

Solution: always activate first with .venv\Scripts\activate (Windows) or source .venv/bin/activate (macOS/Linux) before you start your program.

⚠️ Put .venv in .gitignore

The .venv folder is big (sometimes hundreds of MBs). You should not share it via Git or GitHub. Put .venv in your .gitignore file, so that Git skips it:

.venv/

Your friend just creates their own .venv with uv venv and installs the same packages via the pyproject.toml file that is in Git.

⚠️ Use uv run as a shortcut

No mood to activate and deactivate every time? uv has a handy shortcut:

uv run python main.py

This runs python main.py inside the virtual environment, even when it isn’t activated. uv figures out by itself which environment belongs to the project.

⚠️ Different terminals, different environments

If you activate the environment in one terminal, it is not automatically active in another terminal. You have to activate each terminal separately where you want to use the environment.

Summary

The golden rule: do you see (.venv) in your terminal? Then you’re good. Don’t see it? Activate first, program after.

What’s the difference with virtualenv and pip? Before uv there were already other tools, like virtualenv (for environments) and pip (for packages). With those you could do the same, but you had to use two separate commands and it worked a lot slower. uv does everything in one go, is much faster, and is a lot easier for beginners. That’s why at CoderDojo we prefer uv.

Having problems with your virtual environment? Have a look at Troubleshooting for common errors.