nanoimports

nanoimports is an autonomous, AI-native import layer for Python. It detects missing imports, resolves the import name to the correct pip package, installs the dependency, retries the import, and caches the resolution locally.

from nanoimports import auto, smart_import

pd = smart_import("pandas")
cv2 = smart_import("cv2")
torch = smart_import("torch", lazy=True)

numpy = auto("numpy")

What Works In The MVP

• smart_import() for import, install, retry, and local cache.
• auto() as a minimal ergonomic alias.
• Built-in import-to-package resolution for common mismatches: cv2 -> opencv-python, PIL -> pillow, yaml -> pyyaml, sklearn -> scikit-learn.
• SQLite cache for package resolutions and install logs.
• Installer selection with uv pip install preferred and python -m pip install fallback.
• dry_run mode.
• Lazy import proxy with first-attribute loading.
• Lightweight security checks before installation.
• Repair suggestions for DLL/native extension errors, version conflicts, and missing system deps.
• Conservative sys.meta_path hook used by nanoimports run.
• CLI for running scripts, resolving names, checking the environment, and managing cache.

Install

From a checkout:

python -m pip install -e .

For development:

python -m pip install -e ".[dev]"
pytest

API

from nanoimports import smart_import

cv2 = smart_import("cv2")

When cv2 is missing, nanoimports:

1. catches ModuleNotFoundError;
2. resolves cv2 to opencv-python;
3. records the resolution in SQLite;
4. installs with uv pip install opencv-python or python -m pip install opencv-python;
5. invalidates import caches;
6. retries import cv2.

Use dry_run=True to inspect the planned install without changing the environment:

smart_import("cv2", dry_run=True)

Use install=False to get standard import behavior plus nanoimports diagnostics:

smart_import("pandas", install=False)

Use lazy=True for heavy dependencies:

torch = smart_import("torch", lazy=True)
# torch is imported when an attribute is first accessed

CLI

nanoimports run app.py
nanoimports doctor
nanoimports doctor --json
nanoimports resolve cv2
nanoimports cache list
nanoimports cache clear
nanoimports import cv2 --dry-run

nanoimports run app.py installs a conservative meta-path hook and then executes the script. When Python cannot find a top-level module, the hook resolves and installs it before retrying.

Architecture

The package is intentionally small and modular:

• nanoimports.agents.detection.ImportDetectionAgent normalizes ImportError and ModuleNotFoundError.
• nanoimports.agents.resolution.PackageResolutionAgent resolves import names to pip package names using cache, known mappings, fuzzy matching, and an optional LLM resolver protocol.
• nanoimports.agents.environment.EnvironmentAgent detects the active Python environment and runs uv or pip.
• nanoimports.agents.security.SecurityAgent blocks unsafe package-name syntax and warns about suspicious near-matches.
• nanoimports.agents.repair.RepairAgent suggests fixes for common post-install import failures.
• nanoimports.runtime.lazy.LazyModule defers expensive imports.
• nanoimports.runtime.hooks.NanoImportHook supports autonomous imports while running scripts.
• nanoimports.cache.sqlite.ResolutionCache stores resolutions and install logs.

Cache

By default, cache data is stored at:

~/.cache/nanoimports/nanoimports.sqlite3

Override this with:

NANOIMPORTS_CACHE_DIR=/path/to/cache nanoimports resolve cv2

or with CLI/API cache_path.

Security Model

Runtime installation is powerful. nanoimports keeps the MVP deliberately conservative:

• package names must match a safe package-name pattern;
• known import aliases resolve through explicit mappings;
• suspicious near-matches produce warnings;
• strict_security=True turns warnings into hard failures;
• every install command is logged.

For production services, prefer pinned dependencies and use nanoimports in controlled workflows, developer tools, notebooks, prototypes, or self-healing automation where runtime installation is acceptable.

Stretch Goals

The public API intentionally leaves room for:

• semantic imports such as auto(task="vector database");
• richer PyPI metadata validation;
• notebook integration;
• VS Code extension support;
• dependency graph visualization;
• autonomous repair mode;
• telemetry dashboards.