Virtual Envs and pip

A package is extra Python code someone else wrote. You add it to a project so you do not write everything yourself. json is not a package you install. It is stdlib. httpx is a package. On a laptop you install it. On this site you cannot.

A virtual env (venv) is a private folder of packages. It belongs to one project. Other projects cannot see it. That way version 1 of a package in project A cannot break project B. The language is the same Python. The extra modules are isolated.

Joeven has no pip. This lesson still matters. The agent you ship on a laptop is defined by the packages you pin, not only by the functions you wrote.

What a virtual env is

On your laptop you create a folder, then turn it on:

python -m venv .venv

On Windows, run the activate file inside .venv/Scripts. On macOS and Linux, run source .venv/bin/activate. The command prompt often shows .venv when it is on.

When the venv is on, python and pip use that folder. They do not change the system Python. When you are done, type deactivate.

Do not commit the .venv folder to git. It is large and machine-specific. Commit the list of packages instead. If someone clones your repo and has no requirements file, they cannot rebuild your agent.

python -m venv uses the Python you already have. If python is 3.12, the venv is 3.12. Matching versions across machines reduces “works on my machine.”

pip install

pip is the program that downloads packages into the venv. Prefer python -m pip so you know which Python you are filling.

python -m pip install httpx pytest

httpx talks to HTTP APIs. pytest runs tests. You will meet both ideas in the next lessons. You cannot run these commands in Joeven. This is what you do on a real machine.

Never install a package only because a model named it. Read the name. Bad names exist on purpose: a typo of a popular library that runs extra code at import time. Check the spelling. Check the source. Then pin it.

pip install without a pin grabs “whatever is latest.” Latest changes. A tool that worked on Monday can import-error on Tuesday. Pin for anything you ship.

requirements.txt

A requirements file is a text list of package names and versions. One line per package.

httpx==0.27.2
pytest==8.3.2

== means “this exact version.” Pin versions for an agent you ship. A surprise upgrade can break tools overnight. There are other operators (>=). Exact == is the beginner-safe pin.

Install the whole list:

python -m pip install -r requirements.txt

Lines that start with # are comments. Empty lines are ignored. You will parse that shape in the live box. Real pip also handles extras and hashes. The idea is the same: a text contract of what to install.

A lock goes further: it lists every package those pins pull in, including dependencies of dependencies. This lesson simulates a tiny resolver so you see why “I only installed httpx” still pulled other names.

Joeven has no pip

Joeven runs Python in your browser (Pyodide). There is no pip here. There is no network. You only get the standard library — the modules that come with Python.

Same language. Different sandbox. Code you write here should import json, re, and friends — not httpx. When you copy a lesson to a laptop, you may add HTTP. You still keep the venv.

If an import fails here with ModuleNotFoundError, it is not “run pip.” It is “this module is not in the sandbox.” Use stdlib or simulate with functions, as the HTTP lesson does.

A requirements line without == is a name with no pin. Real pip will fetch latest. Latest is not a version you can replay. For classwork, pins look fussy. For an agent that runs tomorrow, pins are the difference between “search still works” and “an upstream rename broke import.” Put the file in git. Install from the file on every machine, including CI.

python -m pip freeze prints what is actually installed, including transitive names. That dump can become a lock. This lesson’s resolver is freeze in miniature: you asked for httpx, you also got idna. Know that list before you ship.

Common mistakes

• Installing into system Python instead of a venv.
• Committing .venv.
• No pins.
• Installing a name the model invented.
• Assuming Joeven can pip-install.

Run to execute this in your browser. Nothing is sent to a server.

Real pip reads PyPI. Here we simulate. Parse a requirements-like list of strings. Then “resolve” each name with a dict lookup: the dict says what extra packages that name needs. Change a pin. Add a line. Watch unknown-pkg miss the index. That miss is what a lock file is trying to prevent on a real machine.

Never pip install a name a model invented, on a machine that holds secrets. Check the name yourself. Then add it to requirements.txt in git.

How agents use this

Your agent’s packages are part of the product. Pin them. Install the same list on every machine with requirements.txt. Joeven cannot pip-install, so these lessons stay on the standard library. On your laptop, HTTP clients and test tools live in the venv. When a tool works “on my machine,” ask: same requirements file?

A tool that imports httpx is not portable to this browser. Wrap the HTTP client behind a function. In Joeven, that function is fake. On a laptop, it is real. The loop does not care. The venv is where the real client lives.

Version pins also freeze behavior. A parser library that changes JSON defaults can break parse_action without you touching your code. Pin, test, then upgrade on purpose. Agents are programs. Programs have dependencies. Dependencies need a list.