What's the difference between a module and package in Python?

Question

What's the difference between a module and package in Python?

See also: What's the difference between "package" and "module"? (for other languages)

Rego

I might be wrong but for me: a module is basically one python file. A package is a folder with a bunch of modules (python files). – Carnivore

To be considered a package, that folder must contain an __init__.py file. – Allheal

@lc2817: it is the most common case but it is not necessary for a module to be loaded from a file system e.g., see from plumbum.cmd import ls implementation – Vestavestal

@GiulioPiancastelli: In Python 3.3+, namespace packages do not use __init__.py – Vestavestal

How does the community differentiate between Python packages, and packages used to distribute Python components like PyPI/wheels/etc? The two seem like different applications of the word "package" to me. – Urogenital

For the sake of completeness: From Python 3.3 on the folder is not required to contain an __init__.py file to be considered a package. @GiulioPiancastelli. See PEP 420 -- Implicit Namespace Packages – Gonick

Answer 1

A module is a single file (or files) that are imported under one import and used. e.g.

import my_module

A package is a collection of modules in directories that give a package hierarchy.

from my_package.timing.danger.internets import function_of_love

Documentation for modules

Introduction to packages

Vala

When you say: "A module is a single file (or files) that are imported under one import" can you explain the situation where a module is more than one file? Or am I misreading what you mean? – Elisabethelisabethville

What happens when a package folder name contains one or more periods? – Mooney

You don't need a file to create a module e.g., you could import a module from a zip file. Same for packages. There is only one class for modules/packages in Python. Package is just a module with a __path__ attribute. – Vestavestal

@OldGeezer: then it can't be a package, because the name has to be a valid Python identifier. The same applies to any other character outside letters, digits and underscores. – Tancred

Packages are modules too. They are just packaged up differently; they are formed by the combination of a directory plus __init__.py file. They are modules that can contain other modules. – Tancred

The use of underscores is discouraged for package naming, according to PEP8 – Ultimate

@MartijnPieters would you have a link to support that packages are modules too ? I would agree with mareofraft and the documentation that modules are single files. Your remark, even if true, only add confusion – Pulmonic

@Pulmonic sure, see The import system in the reference documentation: It’s important to keep in mind that all packages are modules. – Tancred

@Jacquot: and the glossary on “package”: A Python module which can contain submodules or recursively, subpackages. Technically, a package is a Python module with an __path__ attribute. – Tancred

@Jacquot: there is still only a single file; __init__.py, submodules are separate files (including further packages) inside the package directory. – Tancred

So in your example, is timing a submodule or a subpackage? – Gigi

@Jakob Bowser the link: "introduction to packages" is dead. – Aziza

Answer 2

• Any Python file is a module, its name being the file's base name without the .py extension.
• A package is a collection of Python modules: while a module is a single Python file, a package is a directory of Python modules containing an additional __init__.py file, to distinguish a package from a directory that just happens to contain a bunch of Python scripts. Packages can be nested to any depth, provided that the corresponding directories contain their own __init__.py file.

The distinction between module and package seems to hold just at the file system level. When you import a module or a package, the corresponding object created by Python is always of type module. Note, however, when you import a package, only variables/functions/classes in the __init__.py file of that package are directly visible, not sub-packages or modules.

---

Example

As an example, consider the xml package in the Python standard library: its xml directory contains an __init__.py file and four sub-directories; the sub-directory etree contains an __init__.py file and, among others, an ElementTree.py file.

See what happens when you try to interactively import package/modules:

>>> import xml
>>> type(xml)
<type 'module'>
>>> xml.etree.ElementTree
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
AttributeError: 'module' object has no attribute 'etree'
>>>
>>>
>>> import xml.etree
>>> type(xml.etree)
<type 'module'>
>>> xml.etree.ElementTree
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
AttributeError: 'module' object has no attribute 'ElementTree'
>>>
>>>
>>> import xml.etree.ElementTree
>>> type(xml.etree.ElementTree)
<type 'module'>
>>> xml.etree.ElementTree.parse
<function parse at 0x00B135B0>

---

NOTE

In Python there also are built-in modules, such as sys, that are written in C, but I don't think you meant to consider those in your question.

Allheal

Thanks for explicitly mentioning that the corresponding object created by Python is always of type module. I'm in the process of writing a debugger and was worried that my debugger was incorrect in saying that my packages were modules. – Stefanistefania

"Any Python file is a module" is not a helpful characterization. Python files that contain dashes, like function-of-love.py, cannot be imported and I would't call them modules. It's a useful design pattern to different script files like function-of-love.py which cannot be imported from module files like function_of_love.py, which can be imported. – Hirudin

@Hirudin Python files with a filename containing dashes can still be imported as modules, just not with the usual import statement, because dashes are not allowed in Python identifiers. Use importlib.import_module() instead. – Allheal

@GiulioPiancastelli, are you saying to use dashes for module names is reasonable habit? – Hirudin

@Hirudin I'm not. Where in my comment are you reading that? I'm just saying that, if you happen to have or stumble upon a Python file with dashes in its name, you can still import it as a module. I'm not making a statement about the preferred way of naming a Python file. I'm sure you can find that somewhere else: it is usually strongly advised to avoid dashes in favor of underscores. – Allheal

@GiulioPiancastelli do you agree that it is a common naming convention to have dashes in filenames of Python files which are not meant to be imported? I would be happy to rephrase my above comment from cannot to are not meant to be then. – Hirudin

Being new to Python, sub-packages or modules not being available by default when importing the parent package is what made me stumble. Is there a particular reason for that? And is there a common pattern how to make sub-packages or modules available (via their fully qualified name) when importing the parent package? – Sudan

@Sudan Just import sub-packages in init.py of a parent package. – Laterite

@Laterite But that only works if I have control over the parent package, not if it's a third-party package, right? – Sudan

@Sudan Absolutely. However, it may happen that third-party package author includes such an import in their package. (PS I meant __init__.py of course.) – Laterite

As I explain in my answer below, Python files are not modules. Modules are in-memory objects. Files contain code that is read and executed by the interpreter, which is part of the information used to create a module. The filename and zero or more of the file path components preceding it may (but do not necessarily) contribute to a name which you can use to retrieve the module object and/or the name of the module itself (these are separate things). The always-present module referred to as __main__ is an example of one where the filename does not determine the module name. – Volotta

Super helpful. Just the second half of the first paragraph was enough for me: a package is a directory of Python modules containing an additional init.py file, to distinguish a package from a directory that just happens to contain a bunch of Python scripts. Packages can be nested to any depth, provided that the corresponding directories contain their own init.py file. – Zinfandel

"The distinction between module and package seems to hold just at the file system level." This is wrong. Both "regular" modules and packages may be of type module, but the objects have different attributes (e.g. namespace packages will have a __path__ attribute; a regular module will not) and behaviour (e.g. the different __spec__ values determine the substantially different load behaviour of the two). Some differences are quite user visible: e.g. packages don't produce the '...' is not a package error. – Volotta

Answer 3

First, keep in mind that, in its precise definition, a module is an object in the memory of a Python interpreter, often created by reading one or more files from disk. While we may informally call a disk file such as a/b/c.py a "module," it doesn't actually become one until it's combined with information from several other sources (such as sys.path) to create the module object.

(Note, for example, that two modules with different names can be loaded from the same file, depending on sys.path and other settings. This is exactly what happens with python -m my.module followed by an import my.module in the interpreter; there will be two module objects, __main__ and my.module, both created from the same file on disk, my/module.py.)

A package is a module that may have submodules (including subpackages). Not all modules can do this. As an example, create a small module hierarchy:

$ mkdir -p a/b
$ touch a/b/c.py

Ensure that there are no other files under a. Start a Python 3.4 or later interpreter (e.g., with python3 -i) and examine the results of the following statements:

import a
a                ⇒ <module 'a' (namespace)>
a.b              ⇒ AttributeError: module 'a' has no attribute 'b'
import a.b.c
a.b              ⇒ <module 'a.b' (namespace)>
a.b.c            ⇒ <module 'a.b.c' from '/home/cjs/a/b/c.py'>

Modules a and a.b are packages (in fact, a certain kind of package called a "namespace package," though we wont' worry about that here). However, module a.b.c is not a package. We can demonstrate this by adding another file, a/b.py to the directory structure above and starting a fresh interpreter:

import a.b.c
⇒ ImportError: No module named 'a.b.c'; 'a.b' is not a package
import a.b
a                ⇒ <module 'a' (namespace)>
a.__path__       ⇒ _NamespacePath(['/.../a'])
a.b              ⇒ <module 'a.b' from '/home/cjs/tmp/a/b.py'>
a.b.__path__     ⇒ AttributeError: 'module' object has no attribute '__path__'

Python ensures that all parent modules are loaded before a child module is loaded. Above it finds that a/ is a directory, and so creates a namespace package a, and that a/b.py is a Python source file which it loads and uses to create a (non-package) module a.b. At this point you cannot have a module a.b.c because a.b is not a package, and thus cannot have submodules.

You can also see here that the package module a has a __path__ attribute (packages must have this) but the non-package module a.b does not.

Volotta

If you have not already, go back and work through the examples in this answer. – Scant

Agreed this is a very useful answer because it's driven from examples rather than from generalities. – Nurserymaid

"First, keep in mind that, in its precise definition, a module is an object in the memory of a Python interpreter" - by the same reasoning, [1, 2, 3] is not a list, because a list is an object in the memory of a Python interpreter. Nitpicking at its best. – Allheal

@GiulioPiancastelli Not nitpicking at all: you have missed an essential difference with your example. [1,2,3] includes all the information that is in a list object. A file does not include all the information that is in a module. For example, the name of the module depends on information that exists only in the interpreter, and cannot be determined just from the contents or path of a file. Try following through my examples above and carefully studying the documentation to improve your understanding of modules. – Volotta

Answer 4

From the Python glossary:

It’s important to keep in mind that all packages are modules, but not all modules are packages. Or put another way, packages are just a special kind of module. Specifically, any module that contains a __path__ attribute is considered a package.

Python files with a dash in the name, like my-file.py, cannot be imported with a simple import statement. Code-wise, import my-file is the same as import my - file which will raise an exception. Such files are better characterized as scripts whereas importable files are modules.

Hirudin

Answer 5

The other answers here may still be a bit vague, so I'm posting a hopefully clearer answer. It's important to note that the title of the question is also a bit misleading in the first place, and a better title in my opinion would be: "What is special about package modules compared to regular modules?".

TL;DR - Short Answer:

Packages are modules too, they are however, a special type of them. Special in the sense that 1. they are "directories" and 2. they may contain special files such as __init__.py and __main__.py.

To Better Understand - Longer Answer:

The point is, packages are a special type of modules, so we need to understand modules in general first, and then what's special about the package modules will make sense too. (Notice: I'll sometimes refer to "package modules" in this answer as just "packages", and vice versa)

So let's talk about modules in general first, as it would be less vague / easier to understand. There are basically two things that we do with modules, we either import them in other modules, or execute them directly by Python.

Importing a module has a single obvious goal, accessing what that module has inside.

Executing a module however, usually pursues one of these two goals:

1. That module is a main module and executing it will start our program (or one of its subprograms).
2. We want to try the functionalities of that module in isolation, i.e., without having to import it first.

Let's make more sense of all these through some examples:

Importing modules:

# bar.py

def talk():
    print("bar")

# foo.py

import bar # <-- importing module "bar"

bar.talk() # <-- prints "bar"

Executing Modules

Goal 1, executing a module as a main module:

Let's assume that the foo.py module in the example above, is a main module that starts our program. We can run it by typing this command in the terminal: python3 foo.py # <-- executing a main module and then it will start our program.

Goal 2, trying functionalities of a module in isolation:

Let's assume that we want to try the function talk in the bar.py module in the example above, without running our whole program, i.e., without calling the module foo.py. For that, we'll have to slightly change the bar.py:

# bar.py

def talk():
    print("bar")

if __name__ == '__main__':
    talk()

Now run this command in the terminal: python3 bar.py # <-- trying functionalities of a module in isolation and then it will print bar.

Now that we know what we can do with modules in general, let's return to the main question:

What is special about package modules compared to regular modules?

1. Regular modules in Python are just "files", package modules are however, "directories".

2. Regular modules can be "imported" and can be "executed" (as shown in the examples above), package modules ALSO can be "imported" and can be "executed", HOWEVER, you may rightly complain: "but we can't directly write code in directories! Code is written in files only!", and that's indeed a very good complaint, as it leads us to the second special thing about package modules. The code for a package module is written in files inside its directory, and the names of these files are also reserved by Python. If you want to "import" a package module, you'll have to put its code in an __init__.py file in its directory, and if you want to "execute" a package module, you'll have to put the execution code of it in a __main__.py file in its directory.

And here's the final example for the explanation above:

# hierarchy of files and folders:
.
├── bar_pack/
│   ├── __init__.py
│   ├── __main__.py
│   foo.py

# bar_pack/__init__.py

def talk():
    print("bar")

# bar_pack/__main__.py

import __init__

__init__.talk()

# foo.py

import bar_pack # <-- importing package module "bar_pack"

bar_pack.talk() # <-- prints "bar"

# Run this command in the terminal:
python3 bar_pack # <-- executing the package module "bar_pack", prints "bar"

Hepsibah

this is a fantastic answer! – Benton

You are confusing files with modules here. A file is not a module, it simply information that, along with other information, can be used to create a module, which is an object in memory. Modules need not always be created from files. (See my answer for more details and examples.) – Volotta

Answer 6

A late answer, yet another definition:

A package is represented by an imported top-entity which could either be a self-contained module, or the __init__.py special module as the top-entity from a set of modules within a sub directory structure.

So physically a package is a distribution unit, which provides one or more modules.

Convolve

I feel that there are two definitions for package in Python and they are distinct. Your answer seems to combine them together. Strictly speaking, a python package is a directory with a __init__.py module inside, yet if you talk about distribution units (commonly via PyPI) then this is another type of package entirely (usually defined by the existence of setup.py). I find these two uses of the term package confusing, and I've spoken to some Python beginners who find it utterly bewildering. – Urogenital

@davidA, It's not just how you feel. It's been codified: packaging.python.org/glossary/#term-distribution-package (Thanks for clarifying, too!) – Appetence

Answer 7

Module: A module is a simple Python file with a (.py) extension that contains collections of functions and global variables. It is an executable file, and the notion of Package in Python is used to arrange all of the modules.

For an Example: Save the code in a file called demo (module.py).

def myModule1(name):
    print("My Module name is: "+ name)

Import the demo module module and use the myModule1 function within it.

import demo_module
  
demo_module.myModule1("Math")

Solution:

My Module name is: Math

Package: A package is a basic directory that contains a collection of modules. This directory contains Python modules as well as a (__init .py__) file that the interpreter uses to recognize it as a Package. The package is nothing more than a namespace. Within the package, there are sub-packages.

For an Example:

Student (Package)

| __init__.py (Constructor)

| details.py (Module)

| marks.py (Module)

| collegeDetails.py (Module)

| demo_module.py (Module)

A package is a set of modules organized into directories to form a package directory.

from Student import details, collegeDetails, demo_module

Opsonin

Answer 8

I read the different answers given to this question. The issue is fully covered. But it seems to me that making an extra point may not be a bad idea. If we examine the value of __package__ for different modules, we reach the following result. All of them are module types but for some of them the package is not defined. Check __package__ for "random" and "math".

import cv2
import math
import random
import tkinter as tk

print('cv2:',type(cv2))             # <class 'module'>
print('cv2:',cv2)                   # <module 'cv2.cv2' from 'PATH'>
print('cv2:',cv2.__package__)       # cv2

print('random:',type(random))       # <class 'module'>
print('random:',random)             # <module 'random' from 'PATH'>
print('random:',random.__package__) # [EMPTY]

print('tk:',type(tk))               # <class 'module'>
print('tk:',tk)                     # <module 'tkinter' from 'PATH'>
print('tk:',tk.__package__)         # tkinter

print('math:',type(math))           # <class 'module'>
print('math:',math)                 # <module 'math' (built-in)>
print('math:',math.__package__)     # [EMPTY]

So if we define a folder as follows:

This is how we can see the __package__ output:

import myfolder
import myfolder.script1 as s1
import myfolder.script2 as s2
import myfolder.mySubfolder.script3 as s3

print(type(s1)) # <class 'module'>
print(type(s2)) # <class 'module'>
print(type(s3)) # <class 'module'>

print(s1.__package__) # myfolder
print(s2.__package__) # myfolder
print(s3.__package__) # myfolder.mySubfolder

print(myfolder)                     # <module 'myfolder' (namespace)>
print(myfolder.mySubfolder)         # <module 'myfolder.mySubfolder' (namespace)>
print(myfolder.mySubfolder.script3) # <module 'myfolder.mySubfolder.script3' from 'PATH'>

print(myfolder.__package__)                     # myfolder        
print(myfolder.mySubfolder.__package__)         # myfolder.mySubfolder
print(myfolder.mySubfolder.script3.__package__) # myfolder.mySubfolder

Colatitude

Answer 9

Simply saying below about what the doc says in module and package:

• A module is a file or package(folder).

• A package is the module which can have multiple modules(files and packages(folders)).

And, this is what the doc actually says below in module:

• An object that serves as an organizational unit of Python code. Modules have a namespace containing arbitrary Python objects. Modules are loaded into Python by the process of importing.

And, this is what the doc actually says below in package:

• A Python module which can contain submodules or recursively, subpackages. Technically, a package is a Python module with a path attribute.

Lastly, you can see my answer explaining how to create modules(files and packages) and you can see my answer explaining how to create, upload and install a package for TestPyPI and PyPI

Immobility

Answer 10

I know, it's too late, but a simple answer which would be sufficient for some is:

a module is a file,

a package is a folder.

Comp