Modules, Packages & Virtual Environments

As your Python programs grow, organizing code into multiple files becomes essential. Python's module system makes this natural. Virtual environments keep your project dependencies clean and isolated.

Why This Chapter Matters

Every real Python project uses modules and manages dependencies. Understanding how to structure a project, import code properly, and isolate your environment is foundational for professional development.

What a Module Is

A module is simply a .py file. Any Python file can be imported into another Python file.

project/
├── main.py
├── helpers.py
└── math_utils.py

helpers.py:

def greet(name):
    return f"Hello, {name}!"

AUTHOR = "Nandhoo"

main.py:

import helpers

print(helpers.greet("Asha"))
print(helpers.AUTHOR)

Import Styles

import module

import math
print(math.sqrt(16))   # 4.0
print(math.pi)

from module import name

from math import sqrt, pi
print(sqrt(16))   # 4.0 — no need for math. prefix

from module import * (avoid in production)

from math import *   # imports everything — pollutes namespace

import module as alias

import numpy as np
import pandas as pd

arr = np.array([1, 2, 3])

from module import name as alias

from datetime import datetime as dt
now = dt.now()

The __name__ Guard

Every Python file has a built-in __name__ variable.

• When run directly: __name__ == "__main__"
• When imported: __name__ equals the module name

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

if __name__ == "__main__":
    # This block only runs if you execute this file directly
    # It does NOT run when the file is imported elsewhere
    print(greet("Testing greet"))

This pattern is the standard way to write runnable, importable modules.

Standard Library Modules

Python comes with hundreds of built-in modules. The most commonly used:

import random
print(random.randint(1, 100))
print(random.choice(["apple", "banana", "cherry"]))

from collections import Counter
words = ["cat", "dog", "cat", "bird", "dog", "cat"]
print(Counter(words))   # Counter({'cat': 3, 'dog': 2, 'bird': 1})

from datetime import datetime, timedelta
now = datetime.now()
print(now.strftime("%Y-%m-%d %H:%M:%S"))
next_week = now + timedelta(days=7)

Packages

A package is a directory of modules with an __init__.py file.

myapp/
├── __init__.py
├── models/
│   ├── __init__.py
│   ├── user.py
│   └── post.py
└── utils/
    ├── __init__.py
    └── helpers.py

Import from packages:

from myapp.models.user import User
from myapp.utils import helpers

pip — The Python Package Manager

Install third-party packages from PyPI:

pip install requests
pip install numpy pandas matplotlib
pip install flask

Uninstall:

pip uninstall requests

List installed packages:

pip list
pip show requests

Virtual Environments

A virtual environment is an isolated Python environment for a specific project. It keeps project dependencies separate from each other and from system Python.

Why Virtual Environments Matter

Without one:

• Project A needs requests==2.28
• Project B needs requests==2.31
• You cannot have both globally — they conflict

With venv, each project has its own isolated copy.

Creating a Virtual Environment

# Create the environment
python -m venv venv

# Activate it (macOS / Linux)
source venv/bin/activate

# Activate it (Windows)
venv\Scripts\activate

Your prompt changes to show (venv) indicating the environment is active.

Using the Virtual Environment

# Now pip installs into the venv, not globally
pip install requests flask

# Check what's installed
pip list

Deactivating

deactivate

Never Commit venv to Git

Add to .gitignore:

venv/
__pycache__/
*.pyc
.env

requirements.txt

Share your project's dependencies with others:

# Save current dependencies to a file
pip freeze > requirements.txt

The file looks like:

requests==2.31.0
flask==3.0.0
numpy==1.26.0

Install all dependencies on another machine:

pip install -r requirements.txt

pyproject.toml (Modern Alternative)

Modern Python projects use pyproject.toml for dependency management with tools like poetry or hatch:

[tool.poetry.dependencies]
python = "^3.11"
fastapi = "^0.100.0"

Commonly Used Third-Party Packages

Common Mistakes

• installing packages globally instead of inside a virtual environment
• committing venv/ to version control
• forgetting to activate the virtual environment before pip install
• not saving requirements.txt before sharing the project
• importing with from module import * which pollutes the namespace

Mini Exercises

1. Create a new directory, initialize a virtual environment, and install requests.
2. Write two modules: greetings.py and main.py. Import a function from greetings.py.
3. Add if __name__ == "__main__": to greetings.py with a test call.
4. Run pip freeze > requirements.txt and inspect the output.
5. Use the collections.Counter to count character frequencies in a string.

Review Questions

1. What is the difference between import module and from module import name?
2. What does if __name__ == "__main__": do?
3. Why is it important to use a virtual environment for each project?
4. What is requirements.txt and how do you create one?
5. What does pip install -r requirements.txt do?

Reference Checklist

• I can import modules using all common import styles
• I understand the __name__ guard and why it is used
• I know the most useful standard library modules
• I can create, activate, and deactivate a virtual environment
• I can install packages with pip and save them to requirements.txt
• I know how to structure a project with packages and __init__.py