30 topics

import module
Import an entire module and access with module.name prefix
import module as alias
Import a module with a shorter name
Module vs Script
Understanding __name__ and "if __name__ == __main__"
What Python looks for
How Python resolves "import foo"
from module import name
Import specific names directly with no prefix needed
!from module import *
Import ALL public names from a module (usually avoid this)
from module import name as alias
Import a name and rename it locally
Import specific class/function
Import from nested modules and subpackages
Package structure basics
How to organize Python code into packages with __init__.py
__init__.py purpose
What goes in __init__.py and why
Namespace packages (no __init__.py)
Python 3.3+ allows packages without __init__.py
Relative import basics
Use . and .. to import from the current or parent package
Dot meanings explained
What . (single dot) and .. (double dot) mean in imports
When to use relative vs absolute
Guidelines for choosing between relative and absolute imports
Importing across sibling folders
Import from a folder at the same level using .. (parent) then down
sys.path explained
The list of directories Python searches for modules
!Modify sys.path
Add directories to the import search path at runtime
PYTHONPATH environment variable
Add import paths via environment variable
pip install -e (editable)
The proper way to make your package importable during development
Conditional imports
Import different modules based on availability or platform
Lazy imports
Delay importing until actually needed (faster startup)
Import ordering (PEP 8)
The standard order for import statements
__all__ for public API
Control what "from module import *" exports
Reload a module
Re-import a module after changing its source code
Importing in test files
How tests/ imports from your src/ package (the #1 beginner question)
ModuleNotFoundError
Python cannot find the module you are trying to import
ImportError: cannot import name
The module exists but the specific name does not
Circular imports
Two modules import each other, causing failures
Relative import errors
Common errors when using . and .. imports
!Shadowing built-in modules
When your file name conflicts with a standard library module

Frequently Asked Questions

What is the difference between import and from...import?
"import os" imports the entire module, and you access names via os.path.exists(). "from os.path import exists" imports a specific name directly, and you use exists() without prefix. Use "import" when you need many things from a module (keeps the namespace clean). Use "from...import" when you only need specific items.
What does __init__.py do?
__init__.py marks a directory as a Python package. It runs once when the package is first imported. It can be empty (most common) or contain re-exports to simplify imports. In Python 3.3+, namespace packages work without __init__.py, but it is still recommended to include one for clarity.
What does the dot (.) mean in Python imports?
A single dot (.) means "current package," the directory this file is in. Double dot (..) means "parent package," one directory up. Triple dot (...) means grandparent. These are relative imports and only work inside packages. They are like ./ and ../ in file paths.
Why do I get "attempted relative import with no known parent package"?
This happens when you run a file directly with "python file.py" instead of as a module. Relative imports require package context. Fix: run with "python -m package.module" from the project root, or use absolute imports instead of relative ones.
How do I fix circular imports?
Circular imports happen when A imports B and B imports A. Fixes: (1) Move the import inside a function (lazy import). (2) Import the module instead of the name: "import module" then use "module.name" inside functions. (3) Restructure: move shared code to a third module that both can import. The best fix is usually restructuring.
What is the recommended import order?
PEP 8 recommends: (1) Standard library imports (os, sys, json), blank line, (2) Third-party imports (numpy, flask), blank line, (3) Local/project imports (myapp.models). Within each group, sort alphabetically. Use tools like isort or ruff to auto-sort.

About This Reference

This reference covers everything about Python's import system: basic imports, from...import syntax, package structure with __init__.py, relative imports with . and .., sys.path resolution, common patterns like conditional and lazy imports, and fixes for the most common import errors including ModuleNotFoundError, circular imports, and relative import failures. Each topic includes visual folder tree diagrams to show exactly how imports resolve.