Python Modules and Imports

Basic

As programs grow, putting every function in one file makes the file harder to understand and reuse. Python lets you put related definitions in separate modules and import the parts another program needs. A module is simply a Python file containing definitions and statements.

Your first module

Imagine two files in the same directory. The first file, greetings.py, contains a function. The second file imports that module and uses the function. The module name comes from the filename without .py.

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

import greetings

message = greetings.hello("Maya")
print(message)

This keeps the ownership clear: greetings owns hello, while main.py decides when to call it.

Import the name you need

Python also lets you bind a name directly from a module. from greetings import hello makes hello available without writing the module prefix each time. An alias with as gives an imported module or name a different local name.

from greetings import hello
import greetings as g

print(hello("Maya"))
print(g.hello("Sam"))

A module has its own namespace

A module has its own global namespace. Names defined in one module do not automatically become names in another module. Importing a module gives the importing code access to the module object and its public definitions through that module name.

# prices.py
rate = 0.14

def add_tax(amount):
    return amount * (1 + rate)

import prices

print(prices.rate)
print(prices.add_tax(100))

This separation becomes especially useful when several modules have similarly named functions or variables. The module prefix makes the origin visible and reduces accidental name collisions.

Why imports do not keep running forever

When a module is imported for the first time in an interpreter session, Python initializes it. Later imports of the same module in that session reuse the already imported module rather than executing its top-level code again. This is why changing a module while experimenting in an interactive session can require restarting the interpreter, or deliberately reloading the module with importlib.reload().

When a file is run: __name__

A module can be imported by another module or run directly as a program. Python distinguishes those situations with the special name __name__. When the file is run as the top-level program, __name__ is __main__. When it is imported, __name__ is the module name.

def main():
    print("Running the program")

if __name__ == "__main__":
    main()

This pattern lets one file serve two roles: reusable definitions can be imported, while the guarded part runs only when the file is used as the top-level program.

Run a module with python -m

Python can also execute a module using python -m module_name. The module is then run as the top-level environment. This is useful when the module belongs to a package or when you want to invoke a module by its import name rather than by a filesystem path.

# report.py
def main():
    print("Report ready")

if __name__ == "__main__":
    main()

# Run from the directory containing report.py:
# python -m report

Keep the boundary simple

A useful beginner rule is to give each module a clear responsibility. Put reusable definitions in the module, import what you need, and keep application-starting code behind the __name__ == "__main__" guard. Packages, relative imports, import hooks, and the deeper import machinery build on these ideas and belong later, after the basic module model is comfortable.