Packages and environments

The standard library and everything else

In the modules lesson you imported modules such as math. Modules like that ship with Python, as part of its standard library, so they're always there. Everything else is a package: code someone published for others to install.

Think of an app store for code. Python's public package index is PyPI (the Python Package Index, at pypi.org). It holds hundreds of thousands of packages. The tool that downloads and installs them is pip:

pip install requests

After that, import requests works in your code. Import something that isn't installed and Python stops with a ModuleNotFoundError:

import gradient_magic_toolkit

That error almost always means one of two things. Either the package isn't installed, or it's installed for a different Python than the one running your code. The second one is what the rest of this lesson is about.

Note: The name you install isn't always the name you import. pip install scikit-learn gives you import sklearn, and pip install python-dotenv gives you import dotenv. The package's page on PyPI shows both.

The academy's browser Python already includes the packages lessons need, such as numpy and a version of requests. So you won't install anything here, except in the simulator below.

python3 and pip on a Mac

macOS comes with python3, or offers to install it the first time you type it. You may also have installed newer versions, with the installer from python.org or with Homebrew. Each Python has its own set of installed packages, so it matters which one runs.

python3 --version
which python3

which shows the path of the Python a command will run. Say you install a package, and Python still can't find it. The usual cause is that pip installed it for a different Python than the one running your script. Virtual environments end that confusion.

One environment per project

Imagine two projects. An older reporting script needs numpy version 1.26. A new AI project needs numpy 2.x. If every package is installed in one shared place, only one version can be there, and one project breaks.

The fix is like giving each project its own toolbox. A virtual environment (venv) is a folder inside your project that holds its own set of packages. While it's activated, python and pip in that terminal point at the environment. So whatever you install goes into this project only.

python3 -m venv .venv           # create an environment in a folder called .venv
source .venv/bin/activate       # activate it in this terminal
pip install requests            # installs into .venv only
deactivate                      # go back to the system Python

When an environment is active, your prompt usually starts with its name, like (.venv) sam@MacBook sentiment %. Inside it you can type python and pip. Outside it, stick to python3. Activation lasts only for that terminal window, so you activate again each time you open a new one. (On Windows, the activate command is .venv\Scripts\activate.)

Two rules of thumb:

• One environment per project, created in the project folder, usually named .venv.
• Never commit it to git. It's large and specific to your machine. Add .venv/ to .gitignore, and let others rebuild it from requirements.txt.

requirements.txt

A project records the packages it needs in a file called requirements.txt. It's like a shopping list: one package per line, usually with versions:

requests==2.32.3
numpy>=2.0
anthropic

• == pins an exact version.
• >= sets a minimum.
• A bare name means "whatever is newest".

Pinning versions makes a project reproducible. Someone installing it next year gets the same code you tested with. That matters in AI work, where libraries change quickly, and an upgrade can change behavior.

Two commands work with the file:

pip freeze                         # print every installed package with its exact version
pip install -r requirements.txt    # install everything the file lists

The usual flow for a project you've just cloned: create a venv, activate it, then pip install -r requirements.txt. The simulator above supports both forms.

Note: You'll also meet other tools that do this same job: uv (a fast pip replacement), conda (common in data science) and poetry. The ideas carry over: an isolated environment, plus a file listing what to install. In Jupyter notebooks you'll see %pip install name, which installs into the notebook's environment.

line = "requests==2.32.3"
name, version = line.split("==")
print(version)

Worked example: set up a project you just downloaded

A teammate shares a sentiment project. Its README says "install the requirements and run analyze.py". Here's the whole setup. Lines starting with % are what you type, and the output is trimmed:

% cd ~/projects/sentiment
% python3 -m venv .venv
% source .venv/bin/activate
(.venv) % which python
/Users/sam/projects/sentiment/.venv/bin/python
(.venv) % pip install -r requirements.txt
Successfully installed anthropic requests numpy ...
(.venv) % python analyze.py
Positive: 41  Negative: 9

Step by step:

1. python3 -m venv .venv creates the project's own environment.
2. source .venv/bin/activate switches this terminal to it, and the prompt gains (.venv).
3. which python proves the right Python will run: the path is inside .venv.
4. pip install -r requirements.txt installs the exact list the project needs.
5. Now python analyze.py runs with everything it imports.

Tomorrow, in a new terminal, you only need steps 2 and 5.

Two surprises when installing

The name you install isn't always the name you import. You install scikit-learn but write import sklearn, so a ModuleNotFoundError doesn't always mean it's missing. And activating an environment only lasts for that terminal window, so a new window needs activating again.

Keep .venv out of git

The .venv folder holds thousands of files and only works on your own computer. Commit requirements.txt, and let others rebuild it.