Modules and import

The forms of import, what each one puts in your namespace, and why import * is discouraged.

Overview

The forms of import, what each one puts in your namespace, and why import * is discouraged.

In this guide
  1. The three forms
  2. import * and why not
  3. Imports are cached
  4. Where imports go
  5. The standard library is large
  6. What a module actually is
  7. The __main__ guard
  8. Packages and relative imports
  9. Where Python looks
  10. Import cost
  11. Circular imports, and how to break one
  12. Where installed packages come from
  13. Organising modules of your own
  14. Reading an import error
  15. Questions people ask about Modules and import
  16. Modules and import: recap in one screen

imports.py

imports.py Python 3
Output

                    

import_care.py

import_care.py Python 3
Output

                    

Worth knowing

import math keeps the module name as a prefix, which shows where a function came from.
from math import sqrt puts sqrt straight into your namespace.
import * hides where names came from and silently overwrites your own.
Imports are cached: a module runs once per program, no matter how often it is imported.

Modules and import: A Practical Guide

A module is a file of Python. import runs it once and gives you access to what it defines. The forms of import differ only in what ends up in your namespace. That difference matters more than it first appears.

The three forms

import math            # math.sqrt(9)
from math import sqrt  # sqrt(9)
import numpy as np     # np.array(...)

The first form keeps the module as a namespace prefix. That is a feature, not extra typing. Reading math.sqrt a hundred lines later tells you immediately where the function came from. It cannot collide with any name of your own.

The second form is shorter and appropriate when you use one or two names heavily and there is no ambiguity about where they came from.

as renames on import, either for brevity (numpy as np) or to avoid a clash with a name you already have.

A module is a Python file. When you write import math, Python finds the file that defines math, runs it once, and makes its names available. The second time you import the same module, Python reuses the already-loaded version instead of running the file again.

Packages are directories of modules. A package named email contains modules like email.mime.text. The directory has an __init__.py file that marks it as a package. When you write from email.mime.text import MIMEText, Python walks the directory structure, finds the right file, and pulls out the name.

The import system searches a list of directories stored in sys.path. It checks the current directory first, then the standard library, then installed packages. This order means a file named random.py in your project directory shadows the standard library random module. That shadowing is the most common import bug beginners hit.

Circular imports happen when module A imports module B and module B imports module A. Python can sometimes handle this if the import happens inside a function rather than at the top of the file. But the best fix is usually to reorganize the code so the dependency is one-directional.

This page covers the three import forms, the search path, the shadowing trap, circular imports, and the conventions that keep imports readable.

import * and why not

from math import *

This pulls in each public name at once. Two problems. The second is the serious one.

You can no longer tell where a name came from. sqrt(16) appears from nowhere. Finding its source means guessing which of the star-imports supplied it.

Worse, it silently overwrites. If you defined gamma and then star-import a module that also defines gamma, yours is gone with no warning at all. The page shows just that, printing the function's own output before and after.

The place it's acceptable is an interactive session where you're exploring. Even there it's a habit worth not forming.

Imports are cached

Importing a module twice doesn't run it twice. Python keeps a table in sys.modules and hands back the same module object. So imports are cheap to repeat. Any code at the top level of a module runs just once per program. Which is why putting slow work or side effects at module level is a trap.

Where imports go

At the top of the file, one per line, standard library first, then third-party, then your own. That isn't aesthetics. An import buried inside a function runs on each call and hides a dependency from anyone scanning the file.

The standard library is large

Before installing any of it, check what ships with Python. collections, itertools, datetime, json, random, statistics, pathlib and re cover an huge amount of everyday work. The page uses three of them in six lines.

What a module actually is

A module is a file, and importing it runs that file top to bottom, once. each function meaning, class meaning and top-level statement executes at that moment, and the resulting names become fields of the module object.

That single fact shows a few things at once. It shows why top-level code in a module runs when someone imports it. This Is why print statements left at module level surface in surprising places. It shows why circular imports are a problem: two modules each trying to finish running before the other can. And it shows the caching - having run it once, Python keeps the result.

The __main__ guard

Because importing runs the file, a script that does work at the top level does that work when imported too. The guard blocks it:

def main():
    ...

if __name__ == "__main__":
    main()

__name__ is "__main__" when the file is run right and the module's name when it's imported. So the file can be both a usable script and an importable module, which is what makes it testable - a test can import main without running it.

Packages and relative imports

A directory with an __init__.py is a package, and modules inside it can import from each other fairly:

from . import helpers          # same package
from .models import Record     # a module in the same package

scaled imports only work inside a package and only when the package is being imported, not when a file inside it's run right as a script. That restriction is behind a large share of ImportError: attempted scaled import with no known parent package messages, and the usual answer is to run the module with python -m package.module rather than by path.

Where Python looks

Imports resolve against sys.path. This Starts with the directory of the script being run, then the standard library, then installed packages. The first match wins, and that sorting is why a local file named random.py or json.py shadows the standard library module of the same name and makes errors that look hopeless.

Naming a file after a module you also import is worth avoiding for just this reason - the failure is confusing out of all proportion to the mistake.

Import cost

Imports are cheap after the first. But The first one runs the whole module. A library that does substantial work at import time makes each program that imports it slower to start. This Is why heavy setup belongs in a function the caller chooses to call rather than at module level.

Circular imports, and how to break one

Two modules that each import the other give an error that reads as though a thing is missing when nothing is:

ImportError: cannot import name 'Order' from partially initialized module
'models' (most likely due to a circular import)

The mechanism follows right from "importing runs the file". Module A starts running and hits from B import x. B starts running and hits from A import y — but A is only half-finished. y doesn't exist on it yet. Python has A in sys.modules already. So It doesn't re-run it. It hands back the partial module, and the name is missing.

Three fixes, in order of preference.

Move the shared thing. If A and B both need Order, it belongs in a third module that both import and neither imports back. Most circular imports are a missing module rather than an import problem.

Import inside the function. Moving from B import x into the function that uses it delays it until both modules have finished loading. This works, and it hides a dependency from anyone scanning the file. It's a fix rather than a design.

Import the module, not the name. import B and then B.x at call time often works where from B import x doesn't, because the field is looked up when used rather than when imported.

The one that doesn't work is reordering the imports. This Often moves the error rather than dropping it.

Where installed packages come from

sys.path shows where Python looks. It doesn't explain how any of it got there, and the gap is where most beginner import confusion lives.

pip install requests puts the package into the site-packages directory of whichever Python is running pip. If you've a few Pythons — the system one, one from Homebrew, one from a virtual environment — then "pip installed it and Python can't find it" almost always means two different interpreters. python3 -m pip install x avoids that fully by installing into the interpreter you just named.

A virtual environment is a directory holding its own interpreter link and its own site-packages. python3 -m venv .venv creates one and activating it puts its interpreter first on your PATH. So pip and python both refer to it. The point is alone: two projects can depend on incompatible versions of the same library without either breaking, and the set of packages a project needs is a property of the project rather than of your machine.

The hands-on rules are short. One environment per project. Record the dependencies in a file so the environment can be rebuilt. Never install into the system Python, which your operating system also uses. And when an import fails unexpectedly, python3 -c "import sys. Print(sys.executable)" tells you which interpreter you're really running. This Resolves the question faster than any of it else.

Organising modules of your own

A module is a file. So Organising code is organising files, and a few rules save a lot of trouble.

Group by what things *are for*, not by what they're. A models.py, views.py, utils.py split works until utils.py turns the place all lands. Splitting by feature — orders.py, billing.py — keeps related code together and keeps the imports between files shallow.

Keep module-level code to meanings. any of it that runs work, opens files or makes network calls at import time makes each importer pay for it, including your test suite. Put it in a function and let the caller decide.

Avoid naming a file after a module you also import. A local random.py shadows the standard library one for your whole program, and the resulting AttributeError: module 'random' has no field 'randint' looks hopeless until you spot the file.

And watch the direction of dependencies. If A imports B, B shouldn't need A. When it does, the two are really one module, or there's a third one waiting to be extracted — which is the same conclusion the circular-import section reached from the other direction.

Reading an import error

Four messages cover nearly each import failure, and each points a place exact.

ModuleNotFoundError: No module named 'requests' means Python looked along sys.path and found nothing. Either it isn't installed, or it's installed for a different interpreter. Check with python3 -m pip list using the same python3 that failed.

ImportError: can't import name 'X' from 'y' means the module was found and doesn't hold that name. Either it's a typo, or the version installed is older than the one you're reading about, or it's a circular import and the module is only half-loaded — the message says so when it can.

AttributeError: module 'x' has no field 'y' on a standard-library name is the shadowing case: a file of your own named x.py is earlier on the path than the real module. print(x.__file__) spots it right away.

ImportError: attempted scaled import with no known parent package means a file inside a package was run right by path. Run it as python -m package.module instead.

The common thread is that the message sets apart "couldn't find the module" from "found it, couldn't find the name", and that gap sends you to fully different places. Reading which of the two you've is most of the diagnosis.

Questions people ask about Modules and import

What is __init__.py for? It marks a directory as a package and runs when the package is imported. It can be empty, and since Python 3.3 a package without one mostly works — but including it avoids surprises.

Why does from . import x fail when I run the file? scaled imports need a parent package. This A file run by path doesn't have. Run it with python -m package.module.

Does import run the whole module? Yes, top to bottom, once per program.

How do I reload a module I changed? importlib.reload(module) in an interactive session. In a script, restart it — reloading has enough sharp edges that it isn't worth leaning on.

Where is a module really loaded from? module.__file__ after importing it. This Is the fastest way to confirm you have the one you meant.

Is import x inside a function slow? Only the first time. After that it's a dict lookup in sys.modules.

What is the difference between a module and a package? A module is a file. A package is a directory of modules. Both are imported the same way.

Can a module import itself? It can, and it gets the in part was reset version from sys.modules. There's no good reason to.

What does if TYPE_CHECKING: do? Guards imports that exist only for type hints, so they cost nothing at runtime and can't cause a circular import.

Should I import inside a function to speed up startup? Only for truly heavy optional dependencies. For any of it else the cost is already paid once and the hidden dependency isn't worth it.

Modules and import: recap in one screen

  • Importing runs the file once, top to bottom, and caches the result in sys.modules.
  • import x keeps the prefix and the provenance. from x import y is for one or two heavily used names. import * hides both and can silently overwrite.
  • The __main__ guard is what lets a file be both a script and an importable module.
  • Circular imports mean a shared piece belongs in a third module.
  • One virtual environment per project, and python3 -m pip to be certain which interpreter you're installing into.

Check yourself

0 of 3

Answer without scrolling back up.

  1. What is the main problem with `from module import *`?

  2. What does `import math` put in your namespace?

  3. Importing the same module twice does what?

Cheat sheet

Modules and import

Import a module, understand what Python runs when you do, and organise your own code into files that other scripts can reuse.

PYTHON · vizlearn.in/python/modules_and_import.html

About the author

Ashish Jangra builds and maintains VizLearn. Every module here is written and the visualisation behind it hand-built, so the numbers in a readout come from the same code that draws the picture. Corrections are genuinely welcome and get priority over everything else — if a page states something wrong, or an animation misrepresents what the algorithm does, get in touch.

Teaching a course with this? Individual teachers can use it freely; for a whole department or programme, see institutional licences.