Python Imports Reference

import, from, packages, and fixing common errors - everything you need

How Python Finds Modules

When you write import foo, Python does not simply look for a file named foo.py on disk. Instead, it follows a well-defined import protocol with multiple stages: checking the module cache, consulting a series of finders, and finally using a loader to execute the module code. Understanding this protocol is essential for debugging import errors and controlling module resolution in larger projects.

The Import Protocol (step by step)
============================================================

  import foo
    |
    v
  1. Check sys.modules cache
     +---------------------------+
     | sys.modules['foo']        |
     | exists?                   |
     +---------------------------+
         |              |
        YES             NO
         |              |
         v              v
     Return         2. Iterate sys.meta_path finders
     cached             |
     module              v
                 +-------------------------------+
                 | for finder in sys.meta_path:  |
                 |   spec = finder.find_module() |
                 |   if spec is not None: break  |
                 +-------------------------------+
                         |
                         v
                 3. Finder returns a ModuleSpec
                    (contains loader, origin, submodule_search_locations)
                         |
                         v
                 4. Loader creates module object
                    loader.create_module(spec)
                         |
                         v
                 5. Module added to sys.modules
                    (BEFORE code execution!)
                         |
                         v
                 6. Loader executes module code
                    loader.exec_module(module)
                         |
                         v
                 7. Bind name in caller's namespace
                    caller.foo = sys.modules['foo']

A critical detail: Python inserts the module into sys.modules in step 5, before executing the module body in step 6. This is what makes circular imports partially work. If module B imports module A while A is still loading, B gets the partially initialized module object from the cache rather than triggering an infinite loop.

Default sys.meta_path Finders (in order)
============================================================

  sys.meta_path = [
      BuiltinImporter,     # 1. Built-in modules (sys, _io, etc.)
      FrozenImporter,      # 2. Frozen modules (rarely relevant)
      PathFinder,          # 3. File-system search via sys.path
  ]

  BuiltinImporter
  +-----------------------------------------+
  | Handles modules compiled into the       |
  | Python interpreter itself.              |
  | Examples: sys, _thread, _io, marshal    |
  | These have no .py file on disk.         |
  +-----------------------------------------+
         |
         | not found
         v
  FrozenImporter
  +-----------------------------------------+
  | Handles modules frozen into the binary. |
  | Used internally by Python's bootstrap.  |
  | importlib._bootstrap is a frozen module.|
  +-----------------------------------------+
         |
         | not found
         v
  PathFinder
  +-----------------------------------------+
  | Searches sys.path entries one by one.   |
  | For each path entry, consults           |
  | sys.path_hooks to get a path entry      |
  | finder (typically FileFinder).          |
  | FileFinder looks for .py, .pyc, and     |
  | extension modules (.so / .pyd).         |
  +-----------------------------------------+

Frequently Asked Questions

How does Python decide which module to import when there are name conflicts?

Python follows a strict search order. First, it checks sys.modules for an already-loaded module with that name. If not found, it iterates through sys.meta_path finders in order. The built-in importer checks for built-in modules (like sys and os), the frozen importer checks for frozen modules, and then PathFinder searches each directory in sys.path sequentially. The first match wins. This means a file named random.py in your project directory will shadow the standard library random module because the script directory appears before the stdlib in sys.path.

What is the difference between a regular package and a namespace package in Python?

A regular package is a directory containing an __init__.py file. When Python imports a regular package, it executes __init__.py and uses that directory as the sole location for the package. A namespace package (PEP 420) has no __init__.py file. It allows portions of a package to be spread across multiple directories on sys.path. Python merges all matching directories into a single logical package. Namespace packages are useful for large organizations distributing sub-packages independently, but regular packages are the standard choice for most projects.

Why does Python cache compiled .pyc files and when are they invalidated?

Python compiles .py source files to bytecode (.pyc files) stored in __pycache__ directories. This speeds up subsequent imports because Python can skip the parsing and compilation steps. By default (since Python 3.7), Python uses timestamp-based invalidation: it compares the source file modification time and size stored in the .pyc header against the current .py file. If they match, the cached bytecode is used. You can also enable hash-based invalidation with the --check-hash-based-pycs flag, which computes a hash of the source file instead. The .pyc filename includes the Python version (e.g., module.cpython-313.pyc) so different Python versions do not conflict.

How do I fix a circular import error in Python?

Circular imports happen when module A imports module B and module B imports module A. The fix depends on the situation. The most common approach is to move the import statement inside the function that needs it (lazy import), so it only runs at call time rather than at module load time. Another option is to restructure your code by extracting shared definitions into a third module that both A and B can import without creating a cycle. You can also use TYPE_CHECKING from the typing module: wrap the import in an "if TYPE_CHECKING:" block so it only runs during type checking, not at runtime.

Related Tools

Python DateTime Reference

Dates, times & number formatting

AI & ML Glossary

55+ AI/ML terms explained

Git Commands Reference

70+ git commands with examples

How Python Finds Modules

The Import Protocol (step by step) ============================================================ import foo | v 1. Check sys.modules cache +---------------------------+ | sys.modules['foo'] | | exists? | +---------------------------+ | | YES NO | | v v Return 2. Iterate sys.meta_path finders cached | module v +-------------------------------+ | for finder in sys.meta_path: | | spec = finder.find_module() | | if spec is not None: break | +-------------------------------+ | v 3. Finder returns a ModuleSpec (contains loader, origin, submodule_search_locations) | v 4. Loader creates module object loader.create_module(spec) | v 5. Module added to sys.modules (BEFORE code execution!) | v 6. Loader executes module code loader.exec_module(module) | v 7. Bind name in caller's namespace caller.foo = sys.modules['foo']

Default sys.meta_path Finders (in order) ============================================================ sys.meta_path = [ BuiltinImporter, # 1. Built-in modules (sys, _io, etc.) FrozenImporter, # 2. Frozen modules (rarely relevant) PathFinder, # 3. File-system search via sys.path ] BuiltinImporter +-----------------------------------------+ | Handles modules compiled into the | | Python interpreter itself. | | Examples: sys, _thread, _io, marshal | | These have no .py file on disk. | +-----------------------------------------+ | | not found v FrozenImporter +-----------------------------------------+ | Handles modules frozen into the binary. | | Used internally by Python's bootstrap. | | importlib._bootstrap is a frozen module.| +-----------------------------------------+ | | not found v PathFinder +-----------------------------------------+ | Searches sys.path entries one by one. | | For each path entry, consults | | sys.path_hooks to get a path entry | | finder (typically FileFinder). | | FileFinder looks for .py, .pyc, and | | extension modules (.so / .pyd). | +-----------------------------------------+

Frequently Asked Questions