Skip to content

Restructure the README #2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
aviseth merged 1 commit into from
Aug 24, 2026
Merged

Restructure the README #2

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
248 changes: 141 additions & 107 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,21 +1,33 @@
# importcost

Find out which imports are actually costing you startup time, defer the ones that can be
deferred, and stop the slow ones from coming back.
Measure what your imports cost, defer the safe ones, and stop the slow ones coming back.

Python 3.15 adds `lazy import` ([PEP 810](https://peps.python.org/pep-0810/)). That's the easy
part. The hard part is knowing which of your imports are worth deferring, which ones get loaded
a millisecond later anyway, and which ones quietly break something because they had a side
effect you forgot about. importcost answers all three by running your code, not by reading it.
[![PyPI](https://img.shields.io/pypi/v/importcost.svg)](https://pypi.org/project/importcost/)
[![Python](https://img.shields.io/pypi/pyversions/importcost.svg)](https://pypi.org/project/importcost/)
[![CI](https://github.com/aviseth/importcost/actions/workflows/ci.yml/badge.svg)](https://github.com/aviseth/importcost/actions/workflows/ci.yml)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

Python 3.15 adds `lazy import` ([PEP 810](https://peps.python.org/pep-0810/)), which defers a
module until something touches it. Deciding what to apply it to is the hard part: you cannot tell
by reading code whether deferring an import saves anything, and you cannot tell whether it breaks
something. importcost answers both by running your code.

## Installation

```shell
pip install importcost
```

## Where is my startup time going
Requires Python 3.10+. `audit` and `apply` need a Python 3.15 interpreter for their runtime pass
and fall back to static analysis below that, with a warning.

## Quick start

```shell
importcost profile "import mypkg"
```

```text
$ importcost profile "import mypkg"
import mypkg 418.3 ms of imports across 261 modules (wall 471.2 ms, median of 5)

self ms cumul ms module
Expand All @@ -26,75 +38,73 @@ self ms cumul ms module
9.1 31.4 rich.console
```

`--tree` gives you the nesting if you need to know who pulled in what. `--json` if you want to
pipe it somewhere.

This is `-X importtime` with the interpreter's own baseline subtracted, run five times and
median-ed, because a single run of anything on a laptop is noise.
median-ed, because a single run of anything on a laptop is noise. `--tree` shows the nesting,
`--json` pipes it somewhere.

## Which imports should be lazy
A target can be an import statement, a module, a script, or a console script:

```text
$ importcost audit src --target "import mypkg" --test "pytest -q"
```shell
importcost profile "import pandas"
importcost profile -m mypkg.cli
importcost profile ./scripts/run.py
importcost profile mypy
```

## Deciding what to defer

```shell
importcost audit src --target "import mypkg" --test "pytest -q"
```

```text
saves ms verdict module why
181.9 safe pandas
94.1 safe requests
- no-win rich.console loaded anyway during startup, so deferring it changes nothing
- unsafe mypkg.plugins deferring this breaks the test command; something depends on
its import side effect
- unsafe mypkg.plugins deferring this breaks the test command
- safe tomllib

418.3 ms of imports today. Deferring the safe ones skips 137 module(s), worth about 276.0 ms
at what they cost now.
3 import(s) clear the 0 ms bar.
418.3 ms of imports today. Deferring the safe ones skips 137 modules, worth about 276.0 ms.
3 imports clear the 0 ms bar.
```

The `no-win` and `unsafe` rows are the whole point. Static analysis will happily tell you all
five of those imports can be deferred. Two of them can't, and you'd only find out from a
production traceback.
| Verdict | How it is reached |
| --- | --- |
| `safe` | The module stayed unloaded for the whole run and the test command still passed with it deferred |
| `no-win` | The filter approved the deferral but the module ended up in `sys.modules` anyway, so something else on the startup path needed it |
| `unsafe` | The test command passes normally and fails with this module deferred |
| `not-imported` | Never imported on this path, so there is nothing to win |

Here's how each verdict is reached:
The `no-win` and `unsafe` rows are the point. Static analysis will happily tell you all five of
those imports can be deferred. Two of them cannot, and you would find out from a production
traceback.

- **safe**: the module stayed unloaded for the entire run, and the test command still passed
with it deferred. The saving is what the modules it avoided actually cost in the ordinary
profile, so it's measured rather than guessed at.
- **no-win**: `sys.set_lazy_imports_filter` approved the deferral, but the module ended up in
`sys.modules` before the process exited. Something else on the startup path needed it. You'd
be adding a keyword for nothing.
- **unsafe**: the test command passes normally and fails with this module deferred. When the
whole set fails, importcost bisects to find which modules are responsible rather than making
you delete entries one at a time.
When the whole proposed set fails, importcost bisects to find which modules are responsible, so
the report names them rather than making you delete entries one at a time.

The runtime checks need a 3.15 interpreter. `uv python install 3.15` and pass `--python`.
Without one you get static analysis only, and it says so.
## Applying it

## Make the change

```text
$ importcost apply src --target "import mypkg" --min-saving-ms 5 --write
updated src/mypkg/io.py: pandas
updated src/mypkg/http.py: requests
```shell
importcost apply src --target "import mypkg" --min-saving-ms 5 --write
```

Prints a diff by default; `--write` edits in place. Only touches imports that cleared
`--min-saving-ms`, so you don't end up with forty `lazy` keywords that buy you 3 ms total.

Two output styles:
Prints a diff by default. Only touches imports that cleared `--min-saving-ms`, so you do not end
up with forty `lazy` keywords buying 3 ms in total.

`--style lazy` writes `lazy import pandas`. Needs 3.15.
| Style | Output | Requires |
| --- | --- | --- |
| `--style lazy` | `lazy import pandas` | Python 3.15 |
| `--style lazy-modules` | A `__lazy_modules__` set above the imports | Nothing; valid syntax on 3.9+, active on 3.15+ |

`--style lazy-modules` writes a `__lazy_modules__` set above the imports and leaves the import
statements alone. That's PEP 810's own migration shim: it's ordinary syntax on 3.9, and it only
does anything on 3.15+. Use it for a library that still supports old Pythons. The set comes out
sorted and deduplicated so [flake8-lazy](https://pypi.org/project/flake8-lazy/) doesn't complain
about it.
`lazy-modules` is PEP 810's own migration shim, for a library that still supports old Pythons. The
set comes out sorted and deduplicated so [flake8-lazy](https://pypi.org/project/flake8-lazy/) stays
quiet about it.

## Keep it from creeping back
## Budgets in CI

The reason import time regresses isn't usually a bad commit. It's a dependency upgrade that adds
an at-import metadata fetch, or a new logging integration that costs 50 ms on load. Nothing in
that shows up in code review.
Import time rarely regresses from a bad commit. It regresses when a dependency upgrade adds an
at-import metadata fetch, and nothing about that shows up in review.

```toml
[tool.importcost]
Expand All @@ -103,26 +113,22 @@ max_import_ms = 150
max_modules = 200
```

```text
$ importcost check
ok import mypkg 118.4 ms, 173 modules
```shell
importcost check # ok import mypkg 118.4 ms, 173 modules
importcost check --update # also writes import.lock
```

`importcost check --update` also writes an `import.lock` next to your pyproject.toml recording
exactly which modules get imported. Commit it. After that, a dependency that starts pulling in
something new fails the check with a diff:
`import.lock` records exactly which modules get imported. Commit it. After that, a dependency that
starts pulling in something new fails the check with a diff:

```text
$ importcost check
fail import mypkg 204.7 ms, 189 modules
import time 204.7 ms is over the 150 ms budget by 54.7 ms
imported modules no longer match import.lock (16 new: cryptography, cryptography.fernet,
cryptography.hazmat, ... +13 more). Run 'importcost check --update' if this is intended.
imported modules no longer match import.lock (16 new: cryptography, cryptography.fernet, ...)
+ cryptography, cryptography.fernet, cryptography.hazmat
```

Times vary by machine, so only the numeric budgets are machine-dependent; the module set isn't,
which is why that's the part that gets pinned.
Times vary by machine; the module set does not, which is why that is the part pinned.

Several entry points with different budgets:

Expand All @@ -139,59 +145,87 @@ target = "-m mypkg.cli"
max_import_ms = 400
```

In GitHub Actions:

```yaml
- run: pip install importcost
- run: importcost check
```

Or as a normal test, if you'd rather keep it with everything else:
Or as an ordinary test:

```python
def test_import_stays_cheap(import_budget):
import_budget("import mypkg", max_ms=150, max_modules=200)
```

## How this relates to the other tools
## Configuration

Keys under `[tool.importcost]` in `pyproject.toml`.

| Key | Type | Default | Meaning |
| --- | --- | --- | --- |
| `target` | string | none | What to measure, for the single-budget shorthand |
| `max_import_ms` | number | none | Fail `check` above this import time |
| `max_modules` | integer | none | Fail `check` above this module count |
| `trials` | integer | `5` | Runs per measurement, median taken |
| `python` | string | current | Interpreter to measure with |
| `lock` | string | `"import.lock"` | Path to the lock file |
| `[[tool.importcost.budget]]` | array of tables | none | Several targets, each with its own limits |

## Command reference

| Command | What it does |
| --- | --- |
| `importcost profile <target>` | Show where import time goes, as a table or `--tree` |
| `importcost audit <paths> --target T` | Give every import a verdict, with `--test` to prove safety |
| `importcost apply <paths> --target T` | Rewrite the imports the audit approved, `--write` to edit |
| `importcost check` | Enforce budgets and diff against `import.lock` |

[`flake8-lazy`](https://pypi.org/project/flake8-lazy/) is a linter and a good one. It finds
imports that are unused at module scope and writes `__lazy_modules__` for them. It doesn't
measure anything or run your code, which its author is upfront about. Keep using it. importcost
reads and writes the same `__lazy_modules__` convention, and adds the measurement, the runtime
verification, and the CI guard.
Every command takes `--json`.

`-X importtime` and [`tuna`](https://pypi.org/project/tuna/) show you where the time goes and
leave the rest to you.
## How it compares

## Notes and caveats
| Tool | Measures cost | Finds candidates | Verifies the win | Verifies safety | Applies | CI guard |
| --- | --- | --- | --- | --- | --- | --- |
| `-X importtime` | yes | no | no | no | no | no |
| `tuna` | yes | no | no | no | no | no |
| `flake8-lazy` | no | yes | no | no | yes | no |
| importcost | yes | yes | yes | yes | yes | yes |

`profile` and `check` work on 3.10+. `audit` and `apply` need a 3.15 interpreter for the runtime
pass; below that they fall back to static analysis and warn.
[`flake8-lazy`](https://pypi.org/project/flake8-lazy/) is a good linter and worth keeping.
importcost reads and writes the same `__lazy_modules__` convention and adds the measurement, the
runtime verification and the CI guard.

The audit's safety check is only as good as the command you give `--test`. If your test suite
doesn't touch the code path that relies on an import side effect, neither will importcost.
## Notes

The audit's safety check is only as good as the command given to `--test`. If your suite does not
touch the code path relying on an import side effect, neither will importcost.

Savings are priced from the eager profile rather than by subtracting the two runs. Verifying a
proposal means running the interpreter with a Python-level filter callback on every single
import, and that overhead is about the same size as the saving on a small target, so
subtracting the two just gives you noise. Counting the modules that were genuinely skipped, at what they cost when
they ran, is both stable and closer to what you'll see after the change lands.

Verification is scoped to the file the import came from, not to the module name globally.
Writing `lazy import x` in one file doesn't defer `x` for the rest of the program, and neither
does the check. Otherwise auditing a package would defer the package itself and cheerfully
report that everything got faster.

Imports inside `if TYPE_CHECKING:` are skipped: they already cost nothing. Wildcard imports,
`__future__` imports, and imports inside `try`/`except ImportError` are skipped because PEP 810
doesn't allow deferring them. Names in `__all__` are skipped as a conservative default.

Annotations count as import-time uses unless the file has `from __future__ import annotations`.
On 3.14+ with PEP 649 that's stricter than it needs to be; pass the flag if it's costing you
candidates.

importcost has no runtime dependencies on 3.11+ and enforces its own import budget in CI. A
startup-time tool that takes 200 ms to start isn't a good look.
proposal means running the interpreter with a Python-level filter callback on every import, and on
a small target that overhead is the same size as the saving, so subtracting gives noise. Counting
the modules genuinely skipped, at what they cost when they ran, is stable and closer to what you
will see.

Verification is scoped to the file an import came from, not to the module name globally. Writing
`lazy import x` in one file does not defer `x` for the rest of the program, and neither does the
check. Otherwise auditing a package would defer the package itself and report that everything got
faster.

Imports inside `if TYPE_CHECKING:` are skipped since they already cost nothing. Wildcard imports,
`__future__` imports and imports inside `try`/`except ImportError` are skipped because PEP 810
does not allow deferring them. Names in `__all__` are skipped as a conservative default. So is
`import a, b`, because the statement can only be deferred as a unit but only the first module
would be verified.

Annotations count as import-time uses unless the file has `from __future__ import annotations`. On
3.14+ with PEP 649 that is stricter than necessary; `--assume-lazy-annotations` relaxes it.

Module names are worked out by walking up through `__init__.py` files, which comes out short under
a namespace package. When every candidate returns `not-imported` but the target demonstrably
imports some of them, importcost says so rather than reporting a confident zero.

No runtime dependencies on 3.11+, and CI runs `importcost check` on importcost.

## Contributing

Bug reports and pull requests are welcome. `uv sync` then `uv run pytest`. The runtime tests need
Python 3.15: `uv python install 3.15`.

## License

MIT.
Loading