Python Environments

If you work on more than one Python project, you will eventually hit the moment where one project needs version 1.2 of a library and another needs version 2.0. You upgrade for the new project, and the old one silently breaks. Python environments exist to prevent exactly that moment. They give each project its own isolated set of dependencies so two projects can coexist on the same machine without colliding.

What you'll learn

• Every project gets its own virtual environment: one project, one set of dependencies, zero collisions
• uv venv creates an environment in under a second; uv sync installs exactly what the lockfile says
• Activate an environment before running code in it -- the shell prompt changes to show which environment is active

The problem

You start a new project. You install requests, pandas, and a handful of other packages system-wide. A month later you start another project that needs a newer version of pandas. You upgrade, and now the first project breaks because the newer pandas changed a method name your old code relied on.

This happens because Python, by default, installs packages into a single global location. Every project on the machine shares that same pool of packages. Virtual environments solve this by giving each project its own private copy, isolated from every other project and from the system Python installation.

Options & when to use each

Approach	What it is	When to use it
System Python only	Install everything globally with pip install	Throwaway scripts, one-off experiments where conflicts do not matter
venv (standard library)	Python's built-in environment tool, python -m venv .venv	Works everywhere with no extra install, but slower and heavier than uv
uv venv	Astral's Rust-based environment creator, near-instant	Any project that will live more than a day — the default for this course
conda / Miniconda	Full environment manager that handles Python and non-Python system libraries (CUDA, C++ compilers, etc.)	When your project needs packages with native system dependencies that pip/uv alone can't resolve — common in ML training, geospatial, and some scientific computing

uv venv is what we use throughout the portal. It creates environments faster than the built-in venv module, integrates directly with uv sync for lockfile-driven installs, and does not require any activation gymnastics beyond a single source command. conda is a heavier but capable alternative — if you already have conda workflows you like, you do not need to switch.

Build it

Install uv

If you followed the toolkit setup lesson, uv is already installed. If not:

curl -LsSf https://astral.sh/uv/install.sh | sh

Close and reopen your terminal, or run source ~/.bashrc (or source ~/.zshrc on macOS) so the shell picks up the new binary.

Create a project with an environment

# Create a new project directory and enter it
mkdir my-agent-project && cd my-agent-project

# Initialize a project with a pyproject.toml and a .venv
uv init

# The .venv directory exists now -- but it's not activated yet
ls -d .venv
# Output: .venv

uv init creates three things: a .venv/ directory holding the isolated Python interpreter and package storage, a pyproject.toml for declaring your project metadata and dependencies, and a README.md stub.

Activate the environment

# Linux / macOS / WSL
source .venv/bin/activate

# Your shell prompt now shows the environment name
# (my-agent-project) molsen@host:~/my-agent-project$

While the environment is active, python points to the interpreter inside .venv, and pip (or uv pip) installs into .venv instead of the system. The prompt prefix (my-agent-project) is your visual confirmation that you are inside the environment.

Deactivate when done

deactivate
# The prompt prefix disappears, you're back in the system Python

When to create a new environment

Create a fresh environment any time you start a project that has a different set of dependencies from your existing projects. A good rule of thumb: if you open a new directory to start something new, run uv init (or uv venv for an existing directory) inside it.

# For an existing directory without an environment
cd existing-project
uv venv
source .venv/bin/activate

What goes wrong

Mistake	How you notice it	The fix
Forgot to activate	ModuleNotFoundError even though you installed the package earlier	Run source .venv/bin/activate. Check the prompt -- if you do not see the project name in parentheses, you are not in the environment
Activated the wrong environment	Wrong package version, or package not found	Run which python to see which interpreter is active. If it points somewhere unexpected, deactivate and activate the correct one
Committed .venv/ to git	The .venv/ directory appears in git status	Add .venv/ to .gitignore. Environments should never be committed -- they are rebuilt from pyproject.toml
Used sudo pip install inside an environment	Permissions errors, packages installed outside the environment	Never use sudo with pip. If the environment is active, pip install (or uv add) goes to .venv automatically
Deleted the project directory but not the environment	Disk space slowly disappears	.venv directories live inside the project. Deleting the project directory deletes the environment too. If you use uv venv with --prompt in a non-project location, remember to clean up manually

Confirm it worked

After creating and activating an environment, verify that the interpreter is isolated:

# 1. Confirm the environment is active (look for the name in parentheses)
# 2. Check which python binary is being used
which python
# Should output something like: /home/you/my-agent-project/.venv/bin/python
# NOT /usr/bin/python or /usr/bin/python3

# 3. Verify no global packages leak in
uv pip list
# Should show a clean list with only the packages uv includes by default
# If you see dozens of packages from other projects, the environment is not isolated

Next: Python Package Managers