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.

* Linux aarch64 is available from GitHub Releases only.

Real-world Usage

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

License

MIT