What does CPython's `-X importtime` print, and how do its two time columns differ?

## What the flag does `-X importtime` instruments CPython's import machinery so that every module it actually imports during the process prints a timing line. The report goes to **stderr**, which matters: you can measure a tool whose stdout is piped somewhere without corrupting the pipe. The header line is literally: ``` import time: self [us] | cumulative | imported package ``` and each following line carries two integer microsecond figures and a module name whose indentation shows how deep in the import tree it sits. ## Self versus cumulative **Self** is the time spent executing *that module's own body* — its statements, its class and function definitions, whatever tables it builds, whatever regexes it compiles — plus its own find-and-load overhead, but **excluding** the modules its body imported. **Cumulative** is self plus the cumulative time of every module it was the first to trigger. The two answer different questions: * Cumulative answers **"which import should I stop doing?"** Deferring or deleting a top-level import buys you its cumulative number, not its self number. * Self answers **"who is actually spending the time?"** If a package's `__init__` has a self of 200 microseconds and a cumulative of 300 milliseconds, the package is a façade — it re-exports names from heavy children, and the fix is somewhere below it. If a module has a large *self*, its own body is doing real work at import time, and that is usually code you control and can move into a function. ## Reading the tree The report is emitted as each import **completes**, so a child always appears **above** its parent, indented one level further. Reading it top-down feels backwards; read it as a call tree printed post-order. The last unindented lines are the top-level imports your own code performed, and their cumulative figures are the budget lines that matter. Two consequences follow from "each module is charged to whoever imported it first": * A module imported by two different branches is charged entirely to whichever branch reached it first. Deferring only that branch may move the cost rather than remove it — you have to defer both. * Nothing already in `sys.modules` is listed at all. The interpreter's own startup imports are visible near the top, but a module you imported earlier in the same process shows up once and only once. ## Practical use ```console python -X importtime -c "import csv" 2>&1 | tail -5 ``` Run it more than once. The first run after an edit compiles source to cached bytecode and the numbers are inflated; the steady-state figure is what a user experiences. Instrumentation is not free either — measuring adds a small constant per import, so a tree with a thousand tiny modules reads slightly worse than it is. Compare runs rather than trusting absolute numbers, and compare on the machine and interpreter you deploy on, not on a fast laptop. `PYTHONPROFILEIMPORTTIME=1` is the environment-variable equivalent, which is how you get the report out of a process you cannot re-invoke with different flags — a wrapper script, a container entrypoint, a scheduled job. ## What it does not tell you It measures **import**, not execution. Time your program spends after startup — in the work itself — is invisible here, and steady-state profiling is a different tool. It also does not tell you *why* a module is heavy; for that, read its body. Common answers are: a large table or dataclass hierarchy constructed at import, regexes compiled at module level, a plugin scan walking a directory, a configuration file read, or simply a deep dependency tree where no single module is at fault. Finally, it does not tell you what to do. The report only ranks candidates. The decisions — which imports are part of the eager core, which move into the functions that need them, which module bodies should stop doing work at all — are yours, and they need a target number to be judged against. ## The typical workflow Measure a cold, representative invocation (often `--help`, because it is the cheapest thing your tool can be asked to do and therefore the purest measure of startup). Take the largest cumulative branch at the top level. Ask whether every invocation truly needs it. Move it, re-measure, and keep the before/after numbers — a startup fix that nobody recorded is a startup fix that will be undone.