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.py or email.py, Python will import your local file instead of the real library, crashing with an AttributeError.
  • Committing the .venv/ folder to Git: Never upload the .venv directory to version control; add .venv/ to your .gitignore file and commit requirements.txt instead.
Key takeaways
  • Split growing codebases into focused .py modules and import specific functions or modules explicitly.
  • Always create and activate a python -m venv .venv virtual environment before installing packages with pip.
  • Use if __name__ == "__main__": at the bottom of scripts so functions can be imported safely without side effects.

Related Lessons