PY-01-016-P · Primer — Modules, Imports, pip & venv

The idea in one sentence

A module is just a .py file full of ready-made code you pull into your program with import, and when you need code Python doesn't ship with, pip downloads it while a virtual environment (venv) keeps each project's downloads walled off from every other project's.

Why it exists

Nobody writes everything from scratch — square roots, dates, random numbers, reading web pages, crunching spreadsheets. Someone has already solved these, tested them, and packaged the answer, so the sane move is to reuse rather than reinvent. Python organizes that reusable code into modules (single files) and packages (folders of modules), and import is the one word that says "load that toolbox and let me use it." A huge collection called the standard library comes bundled with Python itself — math, random, json, datetime and hundreds more are always there, no download needed. For everything else — data-science tools like pandas, web frameworks like flask, request libraries like requests — you fetch third-party packages from the internet using pip, Python's package installer. And because two projects often need different, conflicting versions of the same package, a virtual environment gives each project its own private, isolated set of installs so upgrading one project can never quietly break another.

How it works

You bring code in two ways: import math loads the whole module and you reach into it with a dot, math.sqrt(16); from statistics import mean pulls one specific name out so you can call mean(...) directly, no prefix. Standard-library modules just work — they ship with Python — while third-party ones must first be installed with pip install <name> from your terminal. Before installing anything, you create an isolated sandbox with python -m venv .venv, then activate it (source .venv/bin/activate on macOS/Linux, .venv\Scripts\activate on Windows); every pip install after that lands inside .venv and nowhere else. The tiny program below uses only the always-available standard library, so it runs right now with no install:

import math
from statistics import mean

scores = [88, 92, 79, 95]
print(mean(scores))     # 88.5   (from-import: call mean directly)
print(math.sqrt(16))    # 4.0    (dotted access on the whole module)
print(math.gcd(12, 18)) # 6      (greatest common divisor)

Both import styles reached the same standard library; the only difference is whether you kept the math. prefix or lifted one name out of statistics.

The one gotcha

A package you pip install while a virtual environment is not active goes into the wrong place — and forgetting to activate the venv is the number-one reason import mysteriously fails. The symptom is baffling: you clearly ran pip install requests, yet import requests raises ModuleNotFoundError: No module named 'requests'. Almost always the install landed in one Python (say, your system Python) while your script is being run by a different Python (the venv, or vice versa). The fix is a strict habit — create, activate, then install, and confirm which environment you're in:

python -m venv .venv           # 1. create the sandbox (once per project)
source .venv/bin/activate      # 2. activate it (prompt now shows (.venv))
pip install requests           # 3. install INTO the active venv
python -c "import requests; print(requests.__version__)"  # e.g. 2.32.3

If the import still fails, run which python (or where python on Windows): the path should point inside .venv. Also never name your own file after a module you import — a file called random.py will shadow the real random and break your program.

See it — from import to the right package

flowchart TD
    A["I need some code<br/>I didn't write"] --> B{"Does Python ship<br/>with it?"}
    B -->|"Yes: math, json,<br/>random, datetime"| C["Standard library:<br/>just import it"]
    B -->|"No: pandas, flask,<br/>requests"| D["Third-party:<br/>must pip install"]
    D --> E["Create venv:<br/>python -m venv .venv"]
    E --> F["Activate it<br/>(prompt shows .venv)"]
    F --> G["pip install package-name<br/>lands inside .venv"]
    C --> H["import module<br/>or from mod import name"]
    G --> H
    H --> I["Use the code<br/>in your program"]

The one-line takeaway

import reuses code (free from the standard library, or pip install-ed from the internet), and a per-project virtual environment keeps each project's installed packages isolated so they never collide.

Where you'll meet it

You'll meet imports on your very first useful script — import random for a dice roll, import json to read an API response, from datetime import date to stamp a filename — and the top of nearly every Python file you ever open is a little stack of import lines announcing which toolboxes it needs. The moment you follow a tutorial that says pip install pandas or pip install requests, you've stepped into the third-party world, and the very next thing any experienced developer does is spin up a venv first so that project's dependencies stay quarantined. You'll see the payoff when you clone a real project and find a requirements.txt — one pip install -r requirements.txt inside a fresh venv reproduces the exact toolset the authors used. Getting fluent with these four moves — import, standard vs third-party, pip, and venv — is the difference between running toy snippets and running real software, and the activate-then-install habit will save you from the confusing ModuleNotFoundError that stumps almost every beginner at least once.

Named concepts: import and from-import, the standard library and third-party packages, pip installing packages, virtual environments for isolation