Python online course

Importing Modules in Python

Learn how to create a local Python module, import a complete module or selected functions, use namespaces and dot notation, and fix common import errors.

What is a Python module?

A module is a reusable unit of Python code, commonly stored in a source file whose filename ends in .py. A module can group related functions and other code so that an application's main script remains easier to understand.

For example, a file named simple_module.py has the module name simple_module when imported. The .py extension belongs to the filename and is omitted from the import statement.

An import statement is Python syntax that makes a module or one of its names available to the current program. A module created in your own project is called a local module. Python must be able to locate the file before it can import it.

If you are still becoming familiar with functions, review what Python modules are and the basics of writing a Python program.

Create a simple local module

Create a file named simple_module.py. Put it in the same folder as the script or interactive Python session that will import it. Add two greeting-related functions:

def Welcome(name):
    print("Welcome", name)

def Bye(name):
    print("Bye", name)

Each function accepts a parameter named name and prints a message. Once imported, these functions behave like functions defined directly in the importing program.

The basic folder arrangement is:

project_folder/
    simple_module.py
    main.py

Here, main.py can import simple_module because the module file is beside it. The file location and the import name are related but not identical: the file is named simple_module.py, while the import name is simple_module.

Import an entire module

Use the import module_name form to import the complete module:

import simple_module
simple_module.Welcome("Bob")

The output is:

Welcome Bob

This import creates a module namespace. A namespace is a named scope containing identifiers. The functions in simple_module.py are available through that namespace, not as unqualified names in the main script.

Welcome is an attribute of the simple_module module. An attribute is a named object belonging to another object, such as a function belonging to a module. Use dot notation, written as module_name.member_name, to access it:

simple_module.Welcome("Bob")
simple_module.Bye("Bob")

Qualifying a function with its module name makes its origin clear and reduces ambiguity. If several modules contain functions with the same name, the module prefix shows exactly which function the program should use.

Import selected names

Use from module_name import function_name when you want a particular function available directly:

from simple_module import Bye
Bye("John")

The output is:

Bye John

Because Bye was imported into the current namespace, the call does not need the simple_module. prefix. You can import both functions explicitly when both bare names are needed:

from simple_module import Welcome, Bye
Welcome("Bob")
Bye("John")

Importing one name does not make every other module member available by its bare name. For example, importing Bye alone does not define Welcome in the main script.

Understand the unavailable-name error

This code imports only Bye and then tries to call Welcome directly:

from simple_module import Bye
Welcome("John")

Python raises a NameError, similar to:

NameError: name 'Welcome' is not defined

A NameError occurs when code refers to a name that is not defined in the current scope. The Welcome function exists inside simple_module, but the selected-name import did not add Welcome to the main script's namespace.

Fix the problem by importing Welcome explicitly:

from simple_module import Bye, Welcome
Welcome("John")
Bye("John")

Alternatively, import the complete module and use its namespace:

import simple_module
simple_module.Welcome("John")
simple_module.Bye("John")

Make sure Python can find the local module

Python must be able to locate simple_module.py when it processes the import. For this introductory arrangement, place the module beside the importing script:

project_folder/
    simple_module.py
    main.py

In main.py, write:

import simple_module

Do not include the file extension. This is correct:

import simple_module

This is incorrect:

import simple_module.py

Also check the spelling and capitalization of both the filename and function names. The import identifier must correspond to the filename without .py. For example, simple_module.py is imported as simple_module.

Troubleshooting common problems

NameError after importing only Bye

• Symptom: Calling Welcome("John") raises a NameError.
• Cause: Only Bye was added to the current namespace.
• Fix: Use from simple_module import Welcome, Bye, or use import simple_module followed by simple_module.Welcome("John").

Module cannot be imported

• Place simple_module.py beside the importing script for the basic example.
• Use import simple_module, not import simple_module.py.
• Check the filename's spelling and capitalization.
• Confirm that the file was saved with the .py extension rather than as a text file with an additional extension.

Key points

• A module is usually a reusable .py file containing related Python code.
• Use import simple_module to keep members under the module namespace.
• Use simple_module.Welcome() to access an imported module attribute with dot notation.
• Use from simple_module import Bye to call the selected function directly as Bye().
• Selected-name imports do not make unselected names available.
• A NameError means the name is not defined in the current scope.
• For a local module, keep the module file in a location Python can search, such as beside the importing script.