Absolute vs Relative Imports in Python

If you’ve worked on a Python project that has more than one file, chances are you’ve had to use an import statement before.

Even for Pythonistas with a couple of projects under their belt, imports can be confusing! You’re probably reading this because you’d like to gain a deeper understanding of imports in Python, particularly absolute and relative imports.

In this tutorial, you’ll learn the differences between the two, as well as their pros and cons. Let’s dive right in!

Take the Quiz: Test your knowledge with our interactive “Absolute vs Relative Imports in Python” quiz. You’ll receive a score upon completion to help you track your learning progress:

---

Interactive Quiz

Absolute vs Relative Imports in Python

Test your understanding of absolute and relative imports in Python, and learn the syntax, styling, and trade-offs of each approach.

A Quick Recap on Imports

You need to have a good understanding of Python modules and packages to know how imports work. A Python module is a file that has a .py extension, and a Python package is any folder that has modules inside it (or, in Python 2, a folder that contains an __init__.py file).

What happens when you have code in one module that needs to access code in another module or package? You import it!

How Imports Work

But how exactly do imports work? Let’s say you import a module abc like so:

import abc 

The first thing Python will do is look up the name abc in sys.modules. This is a cache of all modules that have been previously imported.

If the name isn’t found in the module cache, Python will proceed to search through a list of built-in modules. These are modules that are compiled directly into the Python interpreter, like sys, and they’re part of the Python Standard Library. If the name still isn’t found in the built-in modules, Python then searches for it in a list of directories defined by sys.path. This list usually includes the current directory, which is searched first.

When Python finds the module, it binds it to a name in the local scope. This means that abc is now defined and can be used in the current file without throwing a NameError.

If the name is never found, you’ll get a ModuleNotFoundError. You can find out more about imports in the Python documentation here!

Syntax of Import Statements

Now that you know how import statements work, let’s explore their syntax. You can import both packages and modules. (Note that importing a package essentially imports the package’s __init__.py file as a module.) You can also import specific objects from a package or module.

There are generally two types of import syntax. When you use the first one, you import the resource directly, like this:

import abc