Build standalone apps

kipferl build packages a Python script for macOS or Linux. The default universal mode produces one executable containing the loader, Rust-hosted PocketPy runtime, and transformed application. The target machine does not need Kipferl, Python, Rust, or Cargo installed.

kipferl build app.py -o app
./app

Project defaults and resources

Inside a project, kipferl build uses the entry and output saved in kipferl.json. An explicit script or -o overrides those values. Local Python modules are included in the application bundle. Add fixed resources with repeatable --asset options or the configuration's assets list:

kipferl build --asset assets --asset templates

Read bundled resources relative to the module's __file__, not the caller's working directory. Static imports are checked before build success, including imports in bundled local modules. See the packaging guide for inclusion boundaries, a complete resource example, and portability checks.

Runtime profiles

Kipferl analyzes static imports and selects one of two prebuilt runtimes. This is profile-based tree shaking: optional Rust dependency trees are removed at compile time, while users still get a fast build without installing a compiler.

The measurements above use the same minimal application and the v0.6 release profile. Exact size varies by target and source payload.

The core profile includes JSON, CSV, XML, INI/configparser, argparse, collections, filesystem/path APIs, subprocess, signals, logging, tui, and the rest of the dependency-light runtime surface. These imports select the full profile:

Kipferl chooses the full profile for dynamic code or import operations such as __import__, importlib, exec, and eval. Relative imports within local packages are resolved during bundling, so they do not automatically force the full runtime. Projects with installed PyPI dependencies select the full runtime used for their compatibility checks. Unsupported static imports fail the build; a larger runtime does not install missing dependencies. The build output shows the selected profile and its reasons.

✓ Runtime profile full (complete compatibility)
  Full runtime: sqlite3 requires the SQLite capability

Use --full-runtime to include every supported built-in capability explicitly. It does not discover local files referenced only by dynamic import names:

kipferl build app.py -o app --full-runtime

Targets

kipferl build app.py -o app-macos --target macos-aarch64
kipferl build app.py -o app-intel --target macos-x86_64
kipferl build app.py -o app-linux --target linux-x86_64
kipferl build app.py -o app-linux-arm --target linux-aarch64

Cross-builds reuse matching local or cached components. If a component is missing, Kipferl offers to download the matching release asset and verifies its SHA-256 checksum before packaging. Linux artifacts are statically linked with musl and do not depend on a target system libc.

Other modes

kipferl build app.py -o app --mode executable
kipferl build app.py -o dist/app-bundled.py --mode single

--full-runtime only applies to universal builds because the other modes do not embed a runtime.