Modules and Imports

Python programs rarely keep all their code in one file. Modules and packages organize reusable code, while import makes that code available to the current program.

import does not search the internet or install software. It can only load code that is already available to the Python interpreter.

The Terms

Python documentation uses several similar terms:

Term	Practical meaning	Example
Script	A Python file executed as the starting program	python app.py
Module	An importable unit of Python code, often one .py file	helpers.py
Import package	A module that can contain submodules or subpackages, usually a directory	shop/
Library	Informal term for reusable code; it may contain several packages and modules	Requests, PyYAML
Distribution package	An installable project obtained by pip or another Python package installer	PyYAML

The word package is overloaded. In pip install PyYAML, it means an installable distribution. In import xml.etree, it refers to Python import packages.

A Small Project

project/
├── .venv/                 virtual environment
├── app.py                 starting script
├── helpers.py             local module
└── shop/                  import package
    ├── __init__.py
    └── formatting.py      submodule

app.py can import the local module and package:

import helpers
from shop import formatting

Third-party modules installed into .venv are also importable while that environment’s Python interpreter is running.

Where Modules Come From

Source	Installed separately?	Example
Python standard library	No; shipped with that Python installation	json, datetime, pathlib
Third-party distribution	Usually yes, in the project’s environment	yaml, provided by PyYAML
Current project	No package download required	helpers.py

Prefer the standard library when it already meets the requirement. Installing another distribution adds versioning, security, and compatibility work.

What import Does

Consider:

import json

At a simplified level, Python:

1. Checks sys.modules, the current interpreter’s cache of loaded modules.
2. If needed, searches built-in modules and locations on the module search path, sys.path.
3. Creates and initializes a module object when it finds the module.
4. Executes the module’s top-level code the first time it is loaded in that interpreter.
5. Stores the module in sys.modules.
6. Binds the name json in the current scope.

import json
    │
    ├─ already in sys.modules? ── yes ──► reuse module object
    │
    └─ no
       └─ search import locations
          ├─ found ─► load, execute, cache, bind name
          └─ missing ─► ModuleNotFoundError

Normal repeated imports reuse the cached module object. They do not rerun all of its top-level code each time.

Key Insight: import loads and binds existing code. It does not download a package, copy its files, or make it available to other Python installations.

Common Import Forms

Import the module

import datetime
 
now = datetime.datetime.now()

The module name remains visible, which makes the origin of datetime.datetime clear.

Import one name

from datetime import datetime
 
now = datetime.now()

This binds the selected name directly. It does not install less code or avoid loading the module.

Use an alias

import xml.etree.ElementTree as ET
 
tree = ET.parse("user.xml")

ET is only a shorter local name. The installed files are unchanged.

Avoid wildcard imports such as from module import *; they make it difficult to see where names came from and can overwrite existing names.

pip install and import Use Different Names

The distribution name on a package index does not have to match the name used by Python:

Install command	Import statement
python -m pip install PyYAML	import yaml
python -m pip install Pillow	from PIL import Image

Package indexes do not guarantee a matching relationship between these names. Do not guess a pip install command from an unfamiliar import statement; check the project’s official installation instructions.

See Installing Packages with pip for what the installation command does.

Diagnosing ModuleNotFoundError

First check which Python interpreter is running and where it searches:

python -c "import sys; print(sys.executable); print(*sys.path, sep='\n')"

Then ask the same interpreter’s pip about the distribution:

python -m pip show PyYAML

Common causes include:

• The distribution was installed for a different Python interpreter.
• The virtual environment is not active.
• The distribution name and import name are different.
• A local file shadows the intended module. For example, a project file named json.py can hide the standard-library json module.
• The module is not installed or is not on sys.path.
• The import contains a spelling or capitalization error.

To see the file that provided an imported module:

python -c "import yaml; print(yaml.__file__)"

What import this Means

this is a small standard-library module. Importing it prints the Zen of Python:

python -c "import this"

This is a demonstration of top-level module code being executed during the first import. It is not a special form of the import statement.

TL;DR

• A module is an importable unit of code; a package can contain modules.
• A library is an informal name for reusable code.
• A distribution package is the installable project handled by tools such as pip.
• import searches the current interpreter’s available locations, loads a module, caches it, and binds a name.
• import does not download or install anything.
• Use python -m pip so the installer and interpreter refer to the same Python environment.
• Distribution names and import names can differ.

Resources

• The Python import system
• Python modules
• Python standard library
• How Python initializes sys.path
• Distribution package vs. import package

Note: Import behaviour and terminology were checked against Python 3.14 and current Python Packaging documentation in July 2026.