Modules, packages, and imports

A module is a file containing Python code, typically ending in dot py. A module can define functions, classes, and variables. Importing a module runs its code once and makes its names available through the module object. Modules are the basic unit of code organization in Python.

A package is a directory containing Python modules and a special init dot py file, which marks the directory as a package. Packages can contain subpackages, forming a hierarchy. Since Python 3.3, namespace packages without an init file are also supported.

Import locates the named module, loads it if not already loaded, executes its top-level code, and binds the module to a name in the current namespace. Imports are cached in sys.modules, so repeating an import does not re-execute the module's code.

Import module binds the module name in the current namespace. From module import name binds specific names from the module without binding the module itself. From module import star imports everything that the module declares public, but it is generally discouraged because it pollutes the namespace.

Absolute imports use the full path from the project root, like from package.subpackage import module. Relative imports use dots to indicate the current or parent package, like from dot import module or from dot dot import sibling. Absolute imports are generally preferred for clarity.

When a Python file is run directly, its dunder name attribute is the string main. When imported as a module, dunder name is the module name. The idiom checks for main to run code only when the file is executed directly, not when it is imported. It is essential for files that are both libraries and scripts.

Python searches the directories listed in sys.path. The first entry is typically the directory of the script being run, followed by the standard library, site-packages, and any directories from the PYTHONPATH environment variable. You can inspect and modify sys.path at runtime.

A virtual environment is an isolated Python installation with its own packages, separate from the system Python. It prevents conflicts between projects that need different versions of the same library. The venv module is built into Python; uv and virtualenv are popular alternative tools.

uv is a fast Python package and project manager written in Rust by Astral, released in 2024. By 2026 it has largely replaced pip, virtualenv, and Poetry in many workflows. It is dramatically faster, supports lockfiles natively, manages Python versions, and provides a unified workflow. Astral was acquired by OpenAI in early 2026. ---