---
id: apipkg
version: "3.0.2"
license: unclear
license_treatment: permissive
maintenance: active
---

# apipkg — apipkg: namespace control and lazy-import mechanism

License: permissive · Maintenance: active · Downloads: 1.6M/mo

## What it is and what it does

apipkg is a small pure Python module that lets you control which names your package exports and when they are imported. Instead of importing everything upfront in your __init__.py, you define a namespace dictionary mapping public names to their import locations as strings, and apipkg defers the actual import until someone accesses that name. This means your package's startup is faster, users only pay the cost of importing what they actually use, and your public API is clearly defined in one place.

The package works by intercepting attribute access on your module and performing the import on demand. It integrates with Python's help() system and command-line completion tools, so users get the same introspection experience as with regular imports. Since it has no runtime dependencies and is only ~200 lines of code, you can also copy it directly into your project if you want to avoid an external dependency.

Use it for:

- Define a clean public API for a package with many internal modules without forcing all imports at startup.
- Reduce import time for packages with heavy dependencies by deferring their loading until needed.
- Organize a large package's namespace hierarchically while keeping the underlying module structure flexible.
- Simplify user code by exposing deeply nested classes or functions at the top level of your package.
- Build plugin systems where submodules are only loaded when explicitly requested.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

apipkg lets you define a package's exported namespace declaratively and defer imports until they are accessed, reducing startup overhead and simplifying your public API.

Yes. apipkg solves a real problem—controlling package namespaces and deferring imports—with zero dependencies, active maintenance, and permissive licensing. It's particularly valuable if you're building a library with many internal modules or heavy dependencies. The code is simple enough to embed if you want to avoid the dependency, but installing it is low-friction and gives you a battle-tested implementation.

## Install

pip install apipkg
uv add apipkg
poetry add apipkg

## Installing apipkg

Before you install: Low friction: pure Python with no runtime dependencies, distributed as a wheel, and actively maintained. Last commit was 2026-08-10 and the repository is not archived.

License in practice: MIT-licensed under permissive terms, so you can use it freely in commercial or open-source projects without restriction.

Quickstart:

pip install apipkg

# In your package's __init__.py:
import apipkg
apipkg.initpkg(__name__, {
    'path': {
        'Class1': "_mypkg.somemodule:Class1",
    }
})

Requires Python 3.7 or later; works on CPython, Jython, and PyPy.

Verify before relying:

- Whether embedding the code directly into your project is practical given the stated ~200 lines of code.
- Performance characteristics of the lazy-loading approach in your specific use case.

## Package facts

- License: not declared (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 1.6M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

lazy import mechanism, namespace control python, deferred module loading, api namespace management, reduce package imports, python import optimization, lazy-loading, namespace-control

[View on SkillFed](https://skillfed.io/packages/apipkg) · [View on PyPI](https://pypi.org/project/apipkg/)