Difference Between a Python Module and a Python Package

In Python, both modules and packages are used to organize and structure code, but they serve slightly different purposes.

A Python module is a single file containing Python code that can be imported and used in other Python code. A module can define variables, functions, classes, and other Python constructs that can be used by other code. Modules are a great way to organize code and make it reusable across multiple programs.

A Python package, on the other hand, is a collection of related Python modules that are organized in a directory hierarchy. A package can contain one or more modules, and may also include other sub?packages. Packages are used to organize larger codebases and to avoid naming conflicts between modules with the same name.

Here are some code examples to illustrate the difference between modules and packages:

Creating a Python module

Example

Let's say we have a file named my_module.py with the following code:

# my_module.py
def hello_world():
    print("Hello, world!")

We can use this module in another Python script by importing it:

# main.py
import my_module
my_module.hello_world()

When we run main.py, it will print ?Hello, world!'. In this case, my_module is a module.

~$python main.py

Output

Hello, world!

Creating a Python package

Now let's say we want to create a package that contains multiple modules. We'll start by creating a directory named my_package with the following structure:

Example

my_package/
??? __init__.py
??? my_module.py

The __init__.py file is required to make my_package a package. It can be empty or contain initialization code for the package.

We can put our hello_world function in my_module.py:

# my_package/my_module.py
def hello_world():
    print("Hello, world!")

And then we can use this package in another Python script by importing the module:

# main.py
from my_package import my_module
my_module.hello_world()

When we run main.py, it will print Hello, world!. In this case, my_package is a package, and my_module is a module inside the package.

~$python main.py

Output

Hello world!

Creating a nested Python package

We can also create nested packages by organizing our modules into subdirectories. For example, let's create a subdirectory named utils inside my_package, with the following structure:

Example

my_package/
??? __init__.py
??? my_module.py
??? utils
    ??? __init__.py
    ??? math_utils.py

The __init__.py file is again required to make utils a sub?package.

We can put some utility functions in math_utils.py:

# my_package/utils/math_utils.py

def add(a, b):
    return a + b

def multiply(a, b):
    return a * b

And then we can use these utilities in another Python script by importing the nested modules:

# main.py
from my_package import my_module
from my_package.utils import math_utils
my_module.hello_world()
result = math_utils.add(2, 3)
print(result)
result = math_utils.multiply(4, 5)
print(result)

When we run main.py, it will print Hello, world!, 5, and 20. In this case, utils is a sub?package inside my_package, and math_utils is a module inside the sub?package.

~$python main.py

Output

Hello, world
5
20

A module is a single file of Python code that can be imported and used in other Python programs. Here's an example of a module:

Example

#my_module.py

def hello(name):
    print(f"Hello, {name}!")

def goodbye(name):
    print(f"Goodbye, {name}!")

You can use this module in another Python program like this:

import my_module
my_module.hello("Alice")  
my_module.goodbye("Bob")   

Output

"Hello, Alice!"
"Goodbye, Bob!"

A package, on the other hand, is a collection of modules that are organized in a directory hierarchy. Here's an example of a package:

Example

my_package/
??? __init__.py
??? module1.py
??? module2.py

The __init__.py file is required to mark the directory as a Python package. Here's what the module1.py and module2.py files might contain:

#module1.py
def add(a, b):
    return a + b

#module2.py
def subtract(a, b):
    return a - b

You can use these modules in another Python program like this:

import my_package.module1
import my_package.module2
print(my_package.module1.add(2, 3))       
print(my_package.module2.subtract(5, 2))  

Output

5
3

Another way to import all modules from a package is to use the from ... import * syntax. For example:

Example

from my_package import *

print(module1.add(2, 3))       
print(module2.subtract(5, 2))  

Output

5
3

This imports all modules from the my_package package into the current namespace. However, this syntax can sometimes lead to naming conflicts and should be used with caution.