# 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)
```bash
uv tool install ux-py
```

### Via pip
```bash
pip install ux-py
```

### From GitHub Releases
Download from [Releases](https://github.com/i2y/ux/releases)

### Build from source
```bash
cargo install --git https://github.com/i2y/ux
```

## Quick Start

### Basic bundling
```bash
# 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:

```bash
# 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](https://github.com/astral-sh/python-build-standalone) for the target platform, so cross-platform offline bundles work from any host.

### Cross-compilation
```bash
# 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
```bash
# 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`:

```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](https://github.com/i2y/ux/releases) only.

## Real-world Usage

- [bkstg](https://github.com/i2y/bkstg) - A serverless desktop Internal Developer Portal built with [Castella](https://github.com/i2y/castella)

## License

MIT
