Modules, Packages and pip

Every chapter of the Python for Beginners series so far has lived in a single file, which works beautifully until a file grows past a few hundred lines. Chapter 13 of this 24-chapter series introduces the three units Python programmers actually ship: modules (one .py file), packages (folders of modules with import rules) and pip, the installer that reaches the Python Package Index.

What a module is

A module is any .py file, and everything Python ships with — math, datetime, json — is a module too. Three import shapes cover daily work: import math loads a module you use through a prefix, from datetime import date pulls out one name, and import random as rnd renames it (the convention behind famous aliases such as numpy as np). In the REPL, typed lines start with >>> and the rest are Python’s replies:

>>> import math
>>> from datetime import date
>>> import random as rnd
>>> math.sqrt(144)
12.0
>>> date(2026, 10, 4)
datetime.date(2026, 10, 4)

Expected output: the reply lines 12.0 and datetime.date(2026, 10, 4). Prefer explicit imports over from module import *: they keep every name traceable to its source.

Writing your own module

Create greeter.py. Nothing marks a file as a module — existing is enough:

# greeter.py
def greet(name):
    return f"Hello, {name}!"

if __name__ == "__main__":
    print(greet("world"))

The last two lines are a main guard. Python sets a module’s __name__ to "__main__" when the file is executed directly and to the module’s own name when it is imported, so the guarded code runs only when you mean it to. The file can be run either way:

python3 greeter.py
python3 -m greeter

Expected output:

Hello, world!
Hello, world!

The first names the file; the second asks the module search path to find and run greeter as a script. The same trick explains two tiny files: demo.py containing print(f"__name__ is {__name__}") prints __name__ is __main__ when run directly, but __name__ is demo when a runner.py containing import demo pulls it in. Imported modules are cached, so that body runs once.

How Python finds your modules

Every import is answered by a search through sys.path, a list of folders visited in a fixed order. The first entry is the folder your script lives in — for python3 -c it is '', meaning the current working directory:

When nothing matches, Python says exactly what it hunted for: ModuleNotFoundError: No module named 'not_a_module'. Note what that first entry implies — python3 scripts/tool.py searches scripts/, not the folder where you typed the command, which is the cause of most baffling import errors.

Packages: modules in folders

Once a project has a dozen modules they move into a folder, and the folder becomes a package. The marker is an __init__.py file, which may be empty but runs when the package is imported — the natural place to expose the public names:

myproject/
├── main.py
└── greeter/
    ├── __init__.py
    ├── casual.py
    └── formal.py

# greeter/__init__.py
from .formal import greet as _formal_greet
from .casual import greet as _casual_greet

def greet(name, formal=True):
    return _formal_greet(name) if formal else _casual_greet(name)

That leading dot makes it a relative import: “look inside this package”. Files outside the package use absolute imports, naming the package in full:

# main.py
from greeter import greet

if __name__ == "__main__":
    print(greet("Ada"))
    print(greet("Linus", formal=False))

Expected output: Good day, Ada. then Hey Linus!. Prefer relative imports inside a package so it can be moved freely, absolute ones outside it — run a package file as a script too early and you get ImportError: attempted relative import with no known parent package.

A tour of the standard library

Everything that arrived with the interpreter is the standard library: hundreds of modules you never install. os handles folders, paths and environment variables; sys describes the running interpreter; math gives roots and constants; random shuffles and samples; datetime handles dates and durations; json turns dictionaries into text and back:

import json, math, os, random, sys
from datetime import datetime, timedelta

print(f"Python {sys.version.split()[0]}, pi {math.pi:.3f}")
print(os.path.join("data", "reports", "q4.csv"))
random.seed(0)
print(random.sample(["a", "b", "c", "d", "e"], 3))
print((datetime(2026, 10, 4, 9, 30) + timedelta(days=100)).isoformat())
print(json.dumps({"name": "Ada", "langs": ["python", "sql"]}))

Expected output: the first line reports your own interpreter version, the rest are deterministic:

Python 3.13.12, pi 3.142
data/reports/q4.csv
['d', 'e', 'a']
2027-01-12T09:30:00
{"name": "Ada", "langs": ["python", "sql"]}

Installing other people’s code with pip

PyPI (the Python Package Index, pronounced “pie Py”) hosts hundreds of thousands of open-source projects. pip ships with Python, and the safe habit is to run it through the interpreter you are using, so packages land where your code will look for them:

python3 -m pip install requests
python3 -m pip show requests

Expected output: download lines are trimmed here; pip resolves and installs the dependencies too, then reports the package metadata (this is Python 3.13 with pip 25.3):

Collecting requests
Collecting charset_normalizer<4,>=2 (from requests)
Installing collected packages: urllib3, idna, charset_normalizer, certifi, requests
Successfully installed certifi-2026.7.22 charset_normalizer-3.5.2 idna-3.20 requests-2.34.2 urllib3-2.8.0
Name: requests
Version: 2.34.2
Summary: Python HTTP for Humans.

Installing gives you a working environment today; pinning gives you the same one tomorrow. pip freeze prints every installed package with its exact version, in the format requirements.txt expects:

python3 -m pip freeze > requirements.txt
cat requirements.txt

Expected output:

certifi==2026.7.22
charset-normalizer==3.5.2
idna==3.20
requests==2.34.2
urllib3==2.8.0

Commit that file: a teammate, or you on a fresh laptop, rebuilds the identical set with python3 -m pip install -r requirements.txt. That habit becomes reliable only once every project has its own environment — exactly what the next chapter builds.

Common mistakes

• Running a bare pip — that executable can belong to a different Python than the one running your code, so packages install but never import; use python3 -m pip.
• Naming a file after a standard-library module — a local json.py or email.py shadows the real one and breaks imports in confusing ways; rename your file.
• from module import * — it hides where names came from and can silently overwrite your own variables; import the names you actually use.
• Circular imports — a.py imports b.py which imports a.py, leaving partially initialised modules and AttributeErrors; move shared code into a third module.
• Assuming the working directory is where your script lives — imports resolve from the script’s folder first, so a helper beside your command can still be invisible.

Practice checklist

1. Write greeter.py, run it directly and with python3 -m greeter, and confirm both print Hello, world!.
2. Reproduce the demo.py / runner.py pair and explain the two __name__ values in one sentence each.
3. Build the greeter package tree, run main.py, then remove one dot from a relative import and read the error.
4. Combine os, random and datetime in one script that prints a random date during 2026 — three standard-library modules, zero installs.
5. Install a package you genuinely want, read its metadata with python3 -m pip show, and compare notes with the JavaScript modules chapter.

What's next?

Modules give you imports and pip gives you other people’s code, but installing into one shared interpreter means projects eventually break each other. Give every project a private interpreter in Virtual Environments and Project Layout.