Virtual Environments and pip 🧪

The problem, first

Project A needs version 1 of a library. Project B needs version 2. If both install into the same Python, one of them breaks. Multiply by twenty projects and several years and you get a machine where nothing works and nobody knows why. This has a name: dependency hell.

A virtual environment is a private Python for one project: its own folder, its own installed packages, isolated from everything else. Making one is one command, and you should make one for every project, every time, no exceptions.

The three commands

# 1. create it (once per project)
python3 -m venv .venv

# 2. activate it (every time you open a terminal)
source .venv/bin/activate        # macOS and Linux
.venv\Scripts\activate           # Windows PowerShell

# 3. install things (they land inside .venv, not on your system)
pip install requests

Once activated, your prompt changes to show it:

$ source .venv/bin/activate
(.venv) $ which python
/Users/you/python-school/.venv/bin/python

(.venv) $ pip install requests
Successfully installed requests-2.32.3 ...

(.venv) $ deactivate
$ 

Never commit it

# .gitignore
.venv/
__pycache__/
*.pyc
.env

A virtual environment contains thousands of files, is specific to your operating system, and can be rebuilt from a text file in seconds. Committing it to git is a classic beginner mistake that makes a repository unusably large.

Recording what you need

(.venv) $ pip freeze > requirements.txt
(.venv) $ cat requirements.txt
certifi==2025.7.9
charset-normalizer==3.4.2
idna==3.10
requests==2.32.3
urllib3==2.5.0

Anyone (including you, on another machine, in a year) can then recreate the exact environment:

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

pip, the essential commands

Using an installed package

# after: pip install requests
import requests

response = requests.get("https://api.github.com/repos/python/cpython")
data = response.json()

print(data["name"], "has", data["stargazers_count"], "stars")

That block has no run button, because the school's in-browser Python has no network access and no third-party packages. This is exactly the point at which doing the ten-minute lab setup starts to pay off. Lesson 42 covers requests properly.

The modern alternative: uv

uv is a drop-in replacement for pip and venv that is typically 10 to 100 times faster, because it is written in Rust. It is increasingly the default choice in new projects.

# the same three ideas, one tool
uv venv                       # create .venv
uv pip install requests       # install into it
uv run script.py              # run with the right environment, no activation needed

# or let it manage the whole project
uv init my-project
uv add requests

Judging a package before you install it

Anyone can publish to PyPI. Packages have been published with names one typo away from popular ones, containing malware. Before installing something you have not heard of:

• Check the name character by character. requests is real. request, requsts and python-requests are the kind of thing attackers register. This is called typosquatting.
• Look at the PyPI page. When was it last released? Does it link to a real source repository?
• Look at the repository. Stars, recent commits, open issues being answered.
• Prefer the standard library when it will do. Zero dependencies is zero supply chain risk.
• Pin your versions in requirements.txt so an update cannot change under you without you noticing.

Common problems

mkdir weather-tool && cd weather-tool
python3 -m venv .venv
source .venv/bin/activate

python -m pip install requests
python -c "import requests; print(requests.__version__)"

pip freeze > requirements.txt
printf '.venv/\n__pycache__/\n' > .gitignore

which python
deactivate

requests==2.32.3
rich>=13.0
pandas
numpy~=1.26.0