monopack

monopack splits a Python monorepo into smaller, entrypoint-focused packages.

Packs are defined by files in packs/ (packs/<name>.py). For each pack, monopack traces imports, copies reachable first-party files, installs only the needed third-party distributions, and writes an isolated build output.

If packs/ is missing, or no pack files are found, the CLI exits with a clear error.

Background

This was inspired by multi-function Lambda packaging, where smaller per-entrypoint artifacts often help cold start performance and reduce package bloat. The same approach works for any Python monorepo where you want tighter per-entrypoint packaging.

Why use it

• Smaller per-pack artifacts from one shared codebase.
• Tighter dependency surface for each pack.
• Easier to inspect what each entrypoint actually ships.

Basic usage

Build one pack:

python -m monopack users_get

Build all discovered packs in packs/*.py:

python -m monopack

Build one pack and skip tests:

python -m monopack users_get --skip-tests

Verify and tests

• --verify (default on): runs a generated verifier script inside the built pack to check importability of selected modules and validate pack entrypoint expectations (including lambda_handler on the pack module).
• tests run by default in an isolated build/<pack_name>_test/ workspace so build artifacts stay clean.
• --skip-tests: skip pack-scoped test execution for faster local loops.

tests/ is required unless test execution is skipped (--skip-tests).

CLI options

Command form:

python -m monopack [pack_name] [options]

Option	Default	Why it is useful
pack_name (positional, optional)	builds all discovered packs	Target a single pack while iterating locally or in CI.
--version	n/a	Print installed CLI version and exit.
--packs-dir	packs	Use a non-default entrypoint directory.
--build-dir	build	Change output location (for CI temp dirs or custom build roots).
--skip-tests	False	Skip pack-scoped tests (tests run by default).
--verify / --no-verify	verify on	Keep safety checks on by default; disable for faster local loops.
--auto-fix	False	Retry missing-module verification failures by updating managed inline config blocks (up to 3 attempts).
--debug	False	Print detailed import and dependency resolution diagnostics to stderr.
--jobs	auto	Parallelize multi-pack builds; set a number for fixed worker count.
--sha-output	hex	Choose deploy digest output format(s): hex, b64, or hex,b64.
--package-manager	auto	Select dependency source flow: auto, pip, uv, poetry, pipenv.
--existing-install-python	unset	Point to an existing Python install to reuse pip cache artifacts during dependency cache sync.

Environment variables are also supported. CLI flags override env vars.

How it works

1. Resolve target packs from packs/ or explicit pack_name.
2. Build an import graph from each pack entrypoint.
3. Copy reachable first-party files into build/<pack_name>/.
4. Resolve third-party import roots to distributions from pinned dependency sync.
5. Install only that per-pack dependency subset into the build target.
6. Run verifier and pack-scoped tests in an isolated build/<pack_name>_test/ workspace (unless --skip-tests).
7. Write zip artifact and optional digest files from the clean runtime build.

More docs

• CLI reference: docs/cli.md
• Fixture-driven testing notes: docs/testing-fixtures.md
• Publishing: docs/publishing.md