ux-py 0.1.5

uv-based Python App Launcher - distribute Python apps as single executables

ux

uv-based Python App Launcher - distribute Python apps as single executables.

Features

• Single binary distribution - End users don't need Python or uv installed
• Offline bundling - Embed Python interpreter and all dependencies; runs without internet access
• Cross-compilation - Build for Linux/Windows from any platform
• macOS .app bundle - Native macOS application with icon support
• Code signing & Notarization - Distribute through macOS Gatekeeper
• DMG creation - Professional macOS distribution format

Installation

Via uv (recommended)

uv tool install ux-py

Via pip

pip install ux-py

From GitHub Releases

Download from Releases

Build from source

cargo install --git https://github.com/i2y/ux

Quick Start

Basic bundling

# Bundle Python app into single binary
ux bundle --project /path/to/project --output ./dist/

Offline bundling

Bundle Python and all dependencies so the app runs without network access on the target machine:

# Embed Python interpreter and locked wheels (no internet required at runtime)
ux bundle --offline --project /path/to/project --output ./dist/

# Cross-compile an offline bundle for Linux
ux bundle --offline --target linux-x86_64 --output ./dist/

The Python interpreter is fetched from python-build-standalone for the target platform, so cross-platform offline bundles work from any host.

Cross-compilation

# Build for Linux (works from any platform)
ux bundle --target linux-x86_64 --output ./dist/

# Build for Windows (works from any platform)
ux bundle --target windows-x86_64 --output ./dist/

macOS .app bundle

# Create .app bundle
ux bundle --format app --output ./dist/

# With code signing
ux bundle --format app --codesign --output ./dist/

# With notarization (requires Apple Developer account)
ux bundle --format app --notarize --output ./dist/

# Create DMG for distribution
ux bundle --format app --codesign --dmg --output ./dist/

Configuration

Add [tool.ux] section to your pyproject.toml:

[project]
name = "myapp"

[project.scripts]
myapp = "myapp.main:main"  # Entry point

[tool.ux]
entry = "myapp"            # Optional: explicit entry point
include = [                # Optional: additional files to include
  "assets/",               # Include entire directory (trailing slash)
  "config.yaml",           # Include specific file
]

[tool.ux.macos]
icon = "assets/icon.png"   # PNG auto-converted to ICNS
bundle_identifier = "com.example.myapp"
bundle_name = "My App"

Included files

The bundle automatically includes:

• Package directory (detected from [project].name, e.g., myapp/ or src/myapp/)
• pyproject.toml, uv.lock
• README.md, LICENSE (if present)

Use [tool.ux].include to add extra files or directories (with trailing slash)

Supported Platforms

ux runs on macOS, Linux, and Windows. You can bundle apps for any supported target from any platform.

Target	Bundle	PyPI
darwin-x86_64	✓	✓
darwin-aarch64	✓	✓
linux-x86_64	✓	✓
linux-aarch64	✓	No*
windows-x86_64	✓	✓

* Linux aarch64 is available from GitHub Releases only.

Real-world Usage

• bkstg - A serverless desktop Internal Developer Portal built with Castella

License

MIT