How does Python import modules straight out of a .zip file on sys.path?

## Two layers, not one Importing from an archive is not a special case bolted onto the import statement; it falls out of the ordinary machinery. `importlib.machinery.PathFinder` sits on `sys.meta_path` and is responsible for everything reachable through `sys.path`. For each entry on that list it needs an object that knows how to search *that kind of* location, and it builds one by calling each callable in `sys.path_hooks` with the entry string until one accepts it. A hook that does not recognise the entry raises `ImportError`, and `PathFinder` moves to the next. The accepted result is stored in `sys.path_importer_cache` keyed by the entry, so the hook runs once per location, not once per import. A stock CPython 3.14 has exactly two hooks: `zipimport.zipimporter`, which accepts a path naming a zip archive, and the hook that produces a `FileFinder` for a directory. That is the whole of the mechanism — the archive support is a path hook and nothing more, which is also the template for adding a location type of your own. ## What zipimport can and cannot do A `zipimport.zipimporter` reads the archive's central directory once and serves `.py` and `.pyc` members from it, including packages: a member `pkg/__init__.py` makes `pkg` importable, and a nested archive path works as a `sys.path` entry too (`lib.zip/subdir` is valid). What it cannot do is just as important: * **No compiled extension modules.** A `.so` or `.pyd` has to be handed to the operating system's dynamic loader, which needs a real file on the filesystem. Archives can only carry pure Python. Tools that ship a single archive work around this by unpacking extensions to a temporary directory first. * **No bytecode caching.** Nothing can be written back into the archive, so a `.py` member is recompiled on every process start unless a matching `.pyc` was placed in the archive when it was built. For a startup-sensitive process, pre-compiling into the archive is the difference that matters. * **No filesystem access to the source.** `__file__` is set to something like `lib.zip/tools.py`. It reads well in a traceback, and tracebacks do show source lines because the loader can supply them, but it is not a path any filesystem call can open. ## The data-file trap The usual way a working package breaks when it is moved into an archive is package data. Code that does `open(os.path.join(os.path.dirname(__file__), "table.json"))` works from a directory and fails from an archive, because that path does not exist. The portable form is `importlib.resources`: `importlib.resources.files("pkg").joinpath("table.json").read_text()` works for both, and when a library genuinely insists on a real filesystem path, `importlib.resources.as_file()` materialises one for the duration of a context manager. Writing package access this way from the start is what keeps the archive option open. ## Caching and invalidation Because the finder for a path entry lives in `sys.path_importer_cache`, and because the archive's directory table is read once, adding a member to an archive that is already on `sys.path` does not make it importable in the running process. `importlib.invalidate_caches()` tells every finder that caches state to drop it, which is the supported way to make a newly written module visible; dropping the specific entry from `sys.path_importer_cache` is the blunter version. This matters for anything that generates code at runtime and for test suites that build fixtures on the fly. ## When it is worth it A single archive gives you one artefact to copy and verify instead of a directory tree, and imports from it are often *faster* than from a directory because one directory table replaces many filesystem lookups. It costs you extension modules, writable bytecode caching and naive data-file access. That trade is usually the right one for a pure-Python internal tool, and the wrong one for an application with compiled dependencies. ## Version notes This mechanism is stable across Python 3.10 to 3.14: two default path hooks, `zipimport.zipimporter` for archives and a directory finder for everything else.