Modules, Packages, pip and Virtual Environments (venv)
Real software does not live inside a single 5,000-line file. As your code grows, you split related functions and classes into separate files (modules) and folders (packages), and you install third-party libraries from the Python Package Index (PyPI). Managing those files and isolating project dependencies with virtual environments is what separates a casual script from a reproducible engineering project.
Modules vs Packages vs Libraries
| Term | What It Is | Example |
|---|---|---|
| Module | Any single .py file whose functions and variables can be imported into other files |
validators.py or built-in math, os, datetime |
| Package | A directory containing multiple related .py modules (traditionally with an __init__.py file) |
monitoring/ containing alerts.py and metrics.py |
| Third-Party Package | External package installed from PyPI using pip |
requests, pytest, pandas, sqlalchemy |
Importing Code Cleanly
# 1. Import the whole module (keeps namespace clean)
import math
print(math.sqrt(16))
# 2. Import specific items directly
from datetime import datetime, timezone
current_utc = datetime.now(timezone.utc)
# 3. Import with a standard alias
import subprocess as sp
Best practice: Never use wildcard imports (from module import *) in production code, as they silently overwrite variables in your current file and make it impossible to tell where a function came from.
Why Every Project Needs a Virtual Environment (venv)
If you install all packages globally on your operating system, Project A (which needs Library v1.0) and Project B (which needs Library v2.0) will clash and break each other. A virtual environment creates an isolated folder inside your project with its own private copy of Python and pip.
# 1. Create a virtual environment named '.venv' inside your project folder
python -m venv .venv
# 2. Activate the environment
# On Windows (Command Prompt / PowerShell):
.venv\Scripts\activate
# On macOS / Linux:
source .venv/bin/activate
# 3. Install packages inside the isolated environment
pip install requests pytest
# 4. Freeze exact versions so teammates can reproduce the setup
pip freeze > requirements.txt
# 5. Install from an existing requirements.txt on another machine
pip install -r requirements.txt
The if __name__ == "__main__": Guard Explained
When Python runs a file directly (python utils.py), it sets the special built-in variable __name__ to "__main__". When that same file is imported by another file (import utils), __name__ is set to the module’s filename ("utils"). Wrapping your execution code inside an if __name__ == "__main__": block allows other scripts to import your helper functions without accidentally running your test or CLI code:
# net_utils.py
def format_endpoint(host: str, port: int) -> str:
return f"https://{host.strip()}:{port}"
if __name__ == "__main__":
# This block runs ONLY when executed directly via: python net_utils.py
print(format_endpoint("api.internal.net", 8443))
Common Mistakes
- Naming your script after a standard library module: If you name your own file
json.py,requests.pyoremail.py, Python will import your local file instead of the real library, crashing with anAttributeError. - Committing the
.venv/folder to Git: Never upload the.venvdirectory to version control; add.venv/to your.gitignorefile and commitrequirements.txtinstead.
- Split growing codebases into focused
.pymodules and import specific functions or modules explicitly. - Always create and activate a
python -m venv .venvvirtual environment before installing packages withpip. - Use
if __name__ == "__main__":at the bottom of scripts so functions can be imported safely without side effects.