Skip to content
Tutorials Center
My learning

Topics

Lesson 2 of 38 ยท Getting Started

Modules, Packages and the Import System

See how Python finds modules with sys.path, how packages and __init__.py work, and build a real package on disk and import it live in the browser.

Before you can package code, you need a clear picture of how Python finds it. Packaging is, at its heart, the art of putting files where the import system will look. If you understand sys.path, __init__.py and relative imports, most installation problems ("it is installed but I cannot import it") become easy to diagnose.

This lesson builds a tiny package from scratch, imports it, and then looks at the machinery. Everything runs live because the standard library is enough.

What import really does

When you write import shapes, Python:

  1. Looks in sys.modules, a cache of everything already imported. A hit returns immediately.
  2. Otherwise asks each finder in sys.meta_path to locate the module. The standard path-based finder walks the directories listed in sys.path, in order, and takes the first match.
  3. Loads the code, creates a module object, stores it in sys.modules, and runs the file top to bottom.

So the rule "first match wins" is the root of many bugs: a file called random.py in your project folder hides the real standard library random, because the script's directory comes first on sys.path.

Python Building a package on disk and importing it

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

We made a directory shapes, put an __init__.py in it, and added the parent directory to sys.path. That is all a package is. Installing a distribution just copies such directories into site-packages, which is already on sys.path.

__init__.py: the package front door

The file runs the first time the package is imported. Use it to:

  • re-export the public names so users write from shapes import circle_area instead of reaching into submodules;
  • define __version__ and __all__;
  • keep heavy imports lazy, so import shapes stays fast.

Keep it light. Everything in it executes for every user of your package.

Regular packages and namespace packages

A directory with __init__.py is a regular package. Since Python 3.3 a directory without one can still be imported as a namespace package, useful when several distributions contribute to one top-level name (company.billing, company.users). For ordinary libraries, add the __init__.py: tools such as type checkers and setuptools auto-discovery behave more predictably.

Absolute and relative imports

Inside a package you can refer to siblings two ways.

Python
# in shapes/square.py
from shapes.circle import area      # absolute: always starts at the top-level name
from .circle import area            # relative: "my sibling named circle"
from . import circle                # the module itself
from .. import something            # one level up (only inside nested packages)

Prefer absolute imports in application code because they read clearly. Relative imports are handy in libraries because they survive renaming the top-level package. A relative import only works when the file is imported as part of a package, not when you run it directly as a script.

Python Relative imports fail in a plain script but work in a package

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

That second case is the infamous "attempted relative import with no known parent package". The fix is never to hack sys.path; run the module as part of the package with python -m tools.b, or install your package properly.

Why sys.path hacks are a smell

You will see answers online telling you to write sys.path.append("..") at the top of scripts. It works on one machine and breaks everywhere else. Packaging gives a better answer: describe your project once, install it into an environment in editable mode (pip install -e .), and Python finds it by name from any working directory.

flowchart TD
    A["import shapes"] --> B{"in sys.modules?"}
    B -- yes --> C["return cached module"]
    B -- no --> D["walk sys.path in order"]
    D --> E{"found shapes/ or shapes.py?"}
    E -- yes --> F["load, store in sys.modules, run"]
    E -- no --> G["ModuleNotFoundError"]

The import algorithm in short: cache first, then the first match along sys.path.

Inspecting the machinery

importlib.util.find_spec tells you where an import would come from without running it. That is perfect for debugging shadowing problems.

Python Where would this import come from?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

When an import returns something unexpected, print module.__file__. It almost always reveals a shadowing file, an old installed copy, or the wrong environment.

Packages need to be findable

Putting it together: packaging is what puts directories with an __init__.py into a site-packages folder. A distribution is that folder content plus metadata. In the next lessons you will install real ones, see how environments pick the folder, and later build your own.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Python imports a module named random from your project folder instead of the standard library one. What is the most likely cause?

    The first match along sys.path wins, and the script's own directory is first. Rename your file.
  2. 2. What does sys.modules do?

    sys.modules maps names to module objects already loaded. It is checked first on every import.
  3. 3. When does from .a import VALUE work?

    Relative imports need a known parent package. Running the file directly gives no parent, so Python raises ImportError.
  4. 4. What is the best long-term alternative to adding sys.path.append('..') in scripts?

    An installed (or editable) package is importable by name from anywhere without path hacks.

Summary

  • import checks sys.modules, then searches sys.path in order; the first match wins.
  • A package is a directory with __init__.py (regular) or without it (namespace).
  • Use __init__.py to expose the public API and __version__; keep it light.
  • Relative imports only work inside a package; run modules with python -m package.module.
  • importlib.util.find_spec and module.__file__ reveal where an import comes from.
  • Installing a distribution places package directories where sys.path already looks.

Next: Installing Packages with pip