How To Import Modules in Python 3

• A module is a single .py file, a package is a directory of modules, and a library is a collection of packages that provide specific functionality.
• Use the pip install <module_name> command to download and install third-party packages from the Python Package Index (PyPI).
• Use the standard import module_name syntax to keep code clear and avoid namespace conflicts, and always avoid wildcard imports.
• Python finds modules by searching a list of directories in sys.path, starting with the current script’s directory, which allows for easy importing of local custom modules.
• Improve code readability by grouping imports at the top of your file in the standard order: standard library, third-party, then local.
• Troubleshoot a ModuleNotFoundError by checking if the module is installed and spelled correctly, and an ImportError by verifying the function’s name.

Before you begin, ensure you have the following prerequisites:

• Python 3 installed on your computer or server.
• A programming environment set up for Python development.

If you need help setting up your environment, refer to these tutorials:

• How to install and set up a local programming environment for Python 3
• How to install Python 3 and set up a programming environment on your server (for Ubuntu, CentOS, Debian, etc.)

A module is any Python file (.py) that contains functions, classes, or variables and can be imported into other Python code. A Python file called hello.py has the module name of hello that can be imported into other Python files or used on the Python command line interpreter. You can learn about creating your modules by reading How To Write Modules in Python 3.

Modules can define functions, classes, and variables that you can reference in other Python .py files or via the Python command line interpreter.

Modules serve as a powerful mechanism to logically arrange your Python code, improving its readability, maintainability, and understandability. Instead of having one massive script, you can break your program down into smaller, more focused modules.

The primary purpose of modules revolves around following software engineering best practices:

• Code reusability: Instead of writing the same function or class multiple times across different parts of your application, you can define it once in a module and then reuse it wherever needed by simply importing that module. This saves time, reduces errors, and makes your codebase cleaner and more efficient.
• Maintainability: By breaking down a large, complex program into smaller, logical modules, you create a more manageable structure. If you need to fix a bug or add a new feature, you know exactly which module to check, rather than sifting through thousands of lines of code.
• Organization: Modules provide a clear and logical way to arrange your Python code. Related functions, classes, and variables can be grouped within a single module, making your project’s structure intuitive and easy to navigate for anyone who needs to understand the codebase.
• Namespace isolation: Each module has its private namespace. This means that variables, functions, and classes defined within one module won’t accidentally conflict with identically named elements in another module, preventing naming collisions and making your code more robust.
• Collaboration: When working on a project, modules allow multiple developers to work on different parts of the application simultaneously without stepping on each other’s toes. Each developer can focus on assigned modules, reducing the risk of accidental conflicts.

While often used interchangeably, “module”, “package”, and “library” have distinct meanings within the Python ecosystem:

• Module: The most granular unit, a module is a single .py file containing Python code. When you import a module, you bring its definitions and statements into your current script’s namespace.
• Package: A package is a collection of related modules organized in a directory hierarchy. The presence of an __init__.py file within a directory signals to Python that it’s a package. This allows for a more structured way to manage multiple modules that work together.
• Library: This is the broadest term, referring to a collection of pre-written code used to perform specific tasks. A library can be composed of single modules, multiple packages, or a mix of both. The Python Standard Library is a prime example, offering a vast array of functionalities. Essentially, all packages are a type of library, burt not all libraries are necessarily structured as multi-module packages.

In Python, modules are accessed by using the import statement. When you do this, you execute the code of the module, keeping the scopes of the definitions so that your current file(s) can make use of these.

There are a number of modules that are built into the Python Standard Library, which contains many modules that provide access to system functionality or provide standardized solutions. The Python Standard Library is part of every Python installation.

Check if a Module is Installed

Before you try to install a module, it’s good practice to check if it’s already on your system. The most direct way to do this is by trying to import it in a Python interactive session.

First, open your command line or terminal and start the Python interpreter:

python3

You should see the Python prompt (>>>), indicating the interpreter is ready for commands.

Let’s first try to import a built-in module, like math.

>>> import math
>>>

Since math is part of the Standard Library, the import succeeds without any message, and you are returned to the prompt. This confirms the module is available.

Now, let’s try to import a popular third-party module that may not be installed, such as matplotlib, a library for data visualization.

>>> import matplotlib

If matplotlib is not installed on your system, the interpreter will raise an ImportError. This is the standard way Python signals that a module could not be found.

Output
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ImportError: No module named 'matplotlib'

Seeing an ImportError is a clear sign that you need to install the module before you can use it.

How to Install the Module Using pip?

pip is the package installer for Python. You use it to install and manage additional libraries and dependencies that are not part of the standard library. These packages are typically downloaded from the Python Package Index (PyPI).

First, exit the Python interpreter. You can do this by typing exit() or by using the shortcut CTRL + D (on Linux/macOS) or CTRL + Z then Enter (on Windows).

Now, from your regular command line prompt, use pip to install matplotlib:

pip install matplotlib

pip will connect to PyPI, download the matplotlib package and any other packages it depends on (its dependencies), and install them into your Python environment.

How to Verify the Installation?

Once the installation is complete, it’s a good idea to verify that the module is now available. Go back into the Python interpreter:

python3

And try the import statement again:

>>> import matplotlib
>>>

This time, the command should complete without any errors, returning you to the prompt. This confirms that matplotlib has been successfully installed and is now ready to be used in your programs.

To use modules in your Python programs, you must first bring them into your script’s scope. This is done using the import statement. Python offers several ways to structure your import statements, each with its specific use case. Understanding these different syntaxes is fundamental to writing clean, efficient, and readable Python code.

This section will cover the primary methods for importing modules and their components.

How to Use import module_name?

The most straightforward way to import a module is with the import keyword followed by the module’s name. This is the recommended approach for most situations.

import math

When you use this syntax, you load the entire module into your program. The module’s contents (its functions, classes, and variables) are kept within their own namespace. To access any of them, you must prefix them with the module’s name and a dot (.). This is known as dot notation.

Let’s create a simple program that uses the math module to calculate the square root of a number and to access the value of Pi.

import math
a = 3
b = 4
a_squared = math.pow(a, 2)
b_squared = math.pow(b, 2)
c = math.sqrt(a_squared + b_squared)
print("The hypotenuse of the triangle is:")
print(c)
print("The value of Pi is:")
print(math.pi)

In this example, we have to use math.pow(), math.sqrt(), and math.pi to access the pow function, the sqrt function, and the pi constant. If we had simply written sqrt(), our program would fail with an error because sqrt is not defined in our program’s main namespace.

When we run the program, we receive the following output:

Output
The hypotenuse of the triangle is:
5.0
The value of Pi is:
3.141592653589793

Using the import module_name syntax is explicit and clear. It makes your code easy to read because it is always obvious where a function or variable is coming from.

How to Use from module_name import function_name?

If you only need one or two specific items from a module and plan to use them frequently, you can import them directly into your program’s namespace using the from ... import syntax.

This approach allows you to call the function or variable by its name, without needing to use dot notation.

Let’s rewrite the previous example by importing only the sqrt and pi items from the math module.

from math import sqrt, pi
a = 3
b = 4
# We can't use math.pow() because we did not import the whole module
# Instead, we can use the built-in exponentiation operator (**)
a_squared = a**2
b_squared = b**2
# Calculate the hypotenuse
c = sqrt(a_squared + b_squared)
print("The hypotenuse of the triangle is:")
print(c)
print("The value of Pi is:")
print(pi)

Notice that we can now use sqrt and pi directly. This can make your code slightly shorter. When you want to import multiple items from the same module, you can separate them with a comma, as we did with from math import sqrt, pi.

The output is identical to the previous example:

Output
The hypotenuse of the triangle is:
5.0
The value of Pi is:
3.141592653589793

While this method can be convenient, it can sometimes make code harder to read if many names are imported from various modules, as it becomes less clear where each function originated.

How to Import All Items with from module_name import *?

Python provides a syntax to import every public function, class, and variable from a module directly into your current namespace. This is done using an asterisk (*), which acts as a wildcard.

# This syntax is generally discouraged
from math import *
c = sqrt(25)
print(pi)

While this might seem like a convenient shortcut, it is strongly discouraged by the Python community’s best practices, including the official PEP 8 style guide. This practice is often referred to as a wildcard import.

There are several significant drawbacks to using wildcard imports:

• Namespace Pollution: It dumps a large number of names into your local namespace. This can make it very difficult to understand which names are defined in your script versus which came from the imported module.
• Reduced Readability: Anyone reading your code (including your future self) will have to guess the origin of a function. Code that explicitly uses math.sqrt() is far clearer than code that just uses sqrt().
• Name Clashes: It dramatically increases the risk of a “naming collision.” If your script defines a function called sqrt() and you then use from math import *, your original function will be silently overwritten by the one from the math module. This can lead to subtle and hard-to-find bugs.

For these reasons, you should avoid wildcard imports in your code. The only exception is for certain modules specifically designed to be used this way, but even then, it should be done with caution. Sticking to import module_name is the safest and most readable approach for professional, maintainable code.

How to Use import module_name as alias?

Sometimes, a module’s name might be very long, or it might conflict with a name you are already using in your code. In these cases, Python allows you to create an alias or an alternate name for the module using the as keyword.

This is extremely common in the data science community, where libraries like numpy, pandas, and matplotlib have conventional aliases.

import numpy as np
import matplotlib.pyplot as plt
# Create a simple array of data using numpy
x = np.array([0, 1, 2, 3, 4])
y = np.array([0, 2, 4, 6, 8])
# Use matplotlib.pyplot to create a plot
plt.plot(x, y)
plt.title("My First Plot")
plt.xlabel("X-axis")
plt.ylabel("Y-axis")
plt.show() 

Here, instead of typing numpy.array(), we can use the much shorter np.array(). Similarly, plt.plot() is used instead of the more verbose matplotlib.pyplot.plot(). This practice makes code cleaner and faster to write without sacrificing readability, as these aliases are widely recognized conventions.

When you write an import my_module statement, how does Python know where to find that file? The answer lies in Python’s module search path, a predefined list of directories where the interpreter looks for modules. The interpreter searches these locations sequentially and uses the first matching file it finds.

The search order is as follows:

• The Current Directory: The directory where the script you are running is located. This is the most common reason you can easily import a file that is in the same folder as your main script.
• PYTHONPATH Directories: A list of directories you can set as an environment variable on your system. This feature allows you to place commonly used custom modules in a central location and access them from any project without modifying sys.path manually.
• Standard Library Directories: The installation-dependent directories where Python’s built-in modules and standard libraries are stored. This is how Python finds modules like math, os, and json.

This list of directories is stored in a variable called path within the built-in sys module. You can inspect this list yourself to see exactly where Python is looking for modules on your system.

import sys
import pprint
print("Python will search for modules in the following directories:")
pprint.pprint(sys.path)

Running this script will print a list of strings, where each string is an absolute path to a directory. The very first item in the list is typically the directory of the script you just ran, which confirms it’s the first place Python searches.

Sample Output
Python will search for modules in the following directories:
['/root/python-code',
 '/usr/lib/python312.zip',
 '/usr/lib/python3.12',
 '/usr/lib/python3.12/lib-dynload',
 '/usr/local/lib/python3.12/dist-packages',
 '/usr/lib/python3/dist-packages']

One of the most powerful features of the import system is the ability to create and use your modules. This is a fundamental practice for organizing code in any application, as it allows you to separate concerns and improve maintainability.

Let’s create a simple project to demonstrate this. Imagine you have the following file structure:

my_app/
├── main.py
└── helpers.py

The helpers.py file contains a function that you want to use in your main application script. Any Python file can act as a module.

# This is a custom module with a helper function
def display_message(message, is_warning=False):
    if is_warning:
        print(f"WARNING: {message}")
    else:
        print(f"INFO: {message}")
# You can also define variables in a module
APP_VERSION = "1.0.2"

Because helpers.py is in the same directory as main.py (the first location in the sys.path search list), you can import it directly without any special configuration.

# Import our custom helpers module
import helpers
# You can also import specific items using the 'from' keyword
from helpers import APP_VERSION
print(f"Starting Application Version: {APP_VERSION}")
# Use a function from the helpers module using dot notation
helpers.display_message("The system is running normally.")
helpers.display_message("Disk space is critically low.", is_warning=True)
print("Application finished.")

When you run main.py, Python will find helpers.py in the current directory, load it as a module, and make its functions and variables available.

Output
Starting Application Version: 1.0.2
INFO: The system is running normally.
WARNING: Disk space is critically low.
Application finished.

This simple pattern is the foundation of creating multi-file applications in Python, allowing you to build clean, maintainable, and well-organized project structures.

Once you are comfortable installing and importing modules, following established best practices will make your code more readable, professional, and easier for others to understand. These conventions are recommended by the official PEP 8 style guide and are designed to prevent common issues.

• Place Imports at the Top: All import statements should be at the very top of your Python file, after any module-level comments or docstrings, but before any code. This gives readers a clear, immediate summary of the file’s dependencies.

• Group and Order Your Imports: A clean, organized import section is a sign of a well-structured project. The standard convention is to group imports into three blocks, separated by a blank line:

  • Standard Library Imports: Modules that are built into Python (e.g., math, os, sys, json).
  • Third-Party Library Imports: Modules you have installed via pip (e.g., numpy, pandas, requests).
  • Local Application Imports: Modules that are part of your project (e.g., from .utils import helper_function).

  Within each group, it’s best practice to sort the imports alphabetically. This makes it easy to find a specific import and prevents duplicate entries.

  good_imports.py

  
  # 1. Standard library imports
  import json
  import os
  from pathlib import Path
  # 2. Third-party imports
  import numpy as np
  import requests
  # 3. Local application imports
  from . import my_module
  from .utils import helper_function
  

• Use Aliases for Clarity and Convention: Use common aliases for well-known libraries to improve readability (e.g., import numpy as np, import pandas as pd). This makes your code more concise while remaining clear to other developers. Avoid creating non-standard aliases (like import numpy as n), as this will confuse other readers who are used to the conventions.

• Be Specific and Avoid Wildcard Imports: When using the from ... import syntax, import only the specific functions or classes you need. Strongly avoid importing everything with from module import *. This practice, known as a wildcard import, pollutes your global namespace, makes it impossible to know where a function comes from, and can lead to hard-to-debug name clashes.

• Use Absolute Imports: Whenever possible, prefer absolute imports (from my_package.utils import helper) over relative imports (from ..utils import helper). Absolute imports are more explicit and do not break if you move your script to a different location within the project.

• Handle Circular Imports and Optional Dependencies: In some advanced cases, you may need to place an import statement somewhere other than the top of the file.

  • Inside a function: If a module is very large and only used in one specific function, importing it locally can speed up the initial load time of your application.
  • To break a circular dependency: If module_a.py imports module_b.py, and module_b.py imports module_a.py, you will get a circular import error. One way to solve this is to move one of the imports inside a function where it’s needed.
  • For optional features: Use a try...except ImportError block to handle optional dependencies. This allows your program to run even if a non-essential library isn’t installed.

• Use Tools to Automate Formatting: Manually sorting imports can be tedious. Modern Python development relies on tools to do this automatically.

  • isort is a popular utility that automatically sorts and groups your imports according to PEP 8 standards.
  • black is a code formatter that, in addition to styling the rest of your code, also handles import formatting.

Integrating these tools into your workflow ensures your code remains clean and consistent with minimal effort.

Even when you follow best practices, you will inevitably encounter errors related to importing modules. Understanding what these errors mean is the key to fixing them quickly.

How to Fix ModuleNotFoundError or ImportError: No module named '...' Errors?

This is the most common import-related error. It means Python looked for the module you asked for but could not find it. Here are the usual causes:

• The module is not installed: You may have forgotten to run pip install <module_name>.
• A typo in the module name: Check your spelling carefully. For example, import matplotlip instead of import matplotlib.
• You are in the wrong virtual environment: This is a very common issue. You may have installed the module in your global Python environment, but are running your script from within a virtual environment (or vice-versa). Make sure your terminal is activated in the correct environment where the package was installed.

How to Fix ImportError: cannot import name '...' from '...' Errors?

This error is different. It means Python found the module but could not find the specific function, class, or variable you tried to import from it.

• A typo in the name: You may have misspelled the function name, e.g., from math import squareroot instead of from math import sqrt.
• Incorrect case: Names are case-sensitive. from MyModule import MyClass is different from from MyModule import myclass.
• The name does not exist: The function or class may have been renamed or removed in a newer version of the library, or it may never have existed. Check the library’s official documentation.
• Circular import: This is a more advanced issue where two modules try to import each other, creating a loop. One module will fail to fully initialize, causing its names to be unavailable.

How to Fix Module Shadowing Errors?

This is a subtle bug that doesn’t always raise an error. It happens when you create a Python file with the same name as a module you want to import.

For example, if you create a file named math.py in your project directory and then try to import math elsewhere in your project, Python will import your local math.py file instead of the built-in standard library module. This will likely cause unexpected behavior or errors.

To avoid this, never name your scripts after existing Python modules, especially common ones from the standard library or popular third-party packages. If you have this issue, simply rename your file.

1. How do I import a built-in module in Python 3?

You can import a built-in module using the import statement followed by the module’s name. Since these modules come with Python, no installation is needed.

For example, to import the built-in math module, you would write:

import math

2. How can I import a function from a module?

To import a specific function, use the from ... import ... syntax. This brings the function directly into your program’s namespace, so you can call it without using the module name as a prefix.

For example, to import only the sqrt function from the math module:

from math import sqrt

You can then use it directly like this: sqrt(25)

3. Why am I getting a ModuleNotFoundError?

This is a very common error that means Python could not find the module you tried to import. The most common reasons are:

1. The module is not installed. You need to install it using pip. For example, pip install requests.
2. A typo in the module name. Double-check that you have spelled the module’s name correctly in your import statement.
3. You are in the wrong Python environment. You may have installed the module in one environment (like your system’s global Python) but are running your script from a different one (like a virtual environment). Make sure you have activated the correct environment where the module is installed.

4. How to import a copy module in Python?

The copy module is part of Python’s standard library and is used to create shallow and deep copies of objects. You can import it directly:

import copy

You can then use its functions, such as copy.copy() for a shallow copy or copy.deepcopy() for a deep copy.

5. How to install the requests module in Python 3?

You can install the requests module using pip from your command line:

pip install requests

After the installation is complete, you can import it into your Python scripts with: import requests

In this tutorial, we have explored the essentials of working with Python modules, from discovery to implementation. You have learned how to check if a module is installed, how to add new ones to your environment using pip, and the various syntaxes for importing them into your programs. We also covered established best practices for organizing your imports and the common patterns that lead to clean, readable, and maintainable code.

By now, you should have a solid understanding of how to troubleshoot common issues, such as an ImportError or ModuleNotFoundError, and how to handle complex situations like module shadowing. With these skills, you are no longer limited to Python’s built-in functions. You can now confidently explore the vast Python Package Index (PyPI), pull in powerful third-party libraries, and integrate them into your projects.

With the foundation you’ve built here, check out the following articles to explore modules in more detail:

• Python Modules — Learn the basics of Python modules, how to import them, and how they help organize and reuse code.
• Python String Module — Discover the powerful string-related functions and constants available in Python’s built-in string module.
• How To Write Modules in Python 3 — Step-by-step guidance on creating your own Python modules to structure and share your code.
• How To Use the collections Module in Python 3 — Explore advanced data structures like namedtuple, deque, Counter, and more with Python’s collections module.