In Python, you use the import keyword to make code in one module available in another. Imports in Python are important for structuring your code effectively. Using imports properly will make you more productive, allowing you to reuse code while keeping your projects maintainable.
This tutorial will provide a thorough overview of Python’s import statement and how it works. The import system is powerful, and you’ll learn how to harness this power. While you’ll cover many of the concepts behind Python’s import system, this tutorial is mostly example driven. You’ll learn from several code examples throughout.
In this tutorial, you’ll learn how to:
- Use modules, packages, and namespace packages
- Handle resources and data files inside your packages
- Import modules dynamically at runtime
- Customize Python’s import system
Throughout the tutorial, you’ll see examples of how to play with the Python import machinery in order to work most efficiently. While all the code is shown in the tutorial, you can also download it by clicking the box below:
Get the Source Code: Click here to get the source code you’ll use to learn about the Python import system in this tutorial.
Basic Python import
Python code is organized into both modules and packages. This section will explain how they differ and how you can work with them.
Later in the tutorial, you’ll see some advanced and lesser-known uses of Python’s import system. However, let’s get started with the basics: importing modules and packages.
Modules
The Python.org glossary defines module as follows:
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. (Source)
In practice, a module usually corresponds to one .py file containing Python code.
The true power of modules is that they can be imported and reused in other code. Consider the following example:
>>> import math
>>> math.pi
3.141592653589793
In the first line, import math, you import the code in the math module and make it available to use. In the second line, you access the pi variable within the math module. math is part of Python’s standard library, which means that it’s always available to import when you’re running Python.
Note that you write math.pi and not just simply pi. In addition to being a module, math acts as a namespace that keeps all the attributes of the module together. Namespaces are useful for keeping your code readable and organized. In the words of Tim Peters:
Namespaces are one honking great idea—let’s do more of those! (Source)
You can list the contents of a namespace with dir():
>>> import math
>>> dir()
['__annotations__', '__builtins__', ..., 'math']
>>> dir(math)
['__doc__', ..., 'nan', 'pi', 'pow', ...]
Using dir() without any argument shows what’s in the global namespace. To see the contents of the math namespace, you use dir(math).
You’ve already seen the most straightforward use of import. However, there are other ways to use it that allow you to import specific parts of a module and to rename the module as you import it.
The following code imports only the pi variable from the math module:
>>> from math import pi
>>> pi
3.141592653589793
>>> math.pi
NameError: name 'math' is not defined
Note that this places pi in the global namespace and not within a math namespace.
You can also rename modules and attributes as they’re imported:
>>> import math as m
>>> m.pi
3.141592653589793
>>> from math import pi as PI
>>> PI
3.141592653589793
For more details about the syntax for importing modules, check out Python Modules and Packages – An Introduction.
Packages
You can use a package to further organize your modules. The Python.org glossary defines package as follows:
A Python module which can contain submodules or recursively, subpackages. Technically, a package is a Python module with an
__path__attribute. (Source)
Note that a package is still a module. As a user, you usually don’t need to worry about whether you’re importing a module or a package.
In practice, a package typically corresponds to a file directory containing Python files and other directories. To create a Python package yourself, you create a directory and a file named __init__.py inside it. The