https://github.com/actepukc/uv-app-starter-pack
Bootstrap PySide6 GUI apps quickly using uv, with built-in PyTorch/CUDA handling.
https://github.com/actepukc/uv-app-starter-pack
astral-uv cross-platform cuda gui pyside6 python pytorch qt6 starter-kit template
Last synced: about 2 months ago
JSON representation
Bootstrap PySide6 GUI apps quickly using uv, with built-in PyTorch/CUDA handling.
- Host: GitHub
- URL: https://github.com/actepukc/uv-app-starter-pack
- Owner: AcTePuKc
- License: cc0-1.0
- Created: 2025-04-06T17:23:51.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-05-29T15:21:41.000Z (about 1 year ago)
- Last Synced: 2025-06-18T13:06:28.547Z (about 1 year ago)
- Topics: astral-uv, cross-platform, cuda, gui, pyside6, python, pytorch, qt6, starter-kit, template
- Language: Python
- Homepage:
- Size: 21.5 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 📦 UV-App-Starter-Pack
A clean, cross-platform Python GUI app bootstrapper using **PySide6** and **uv**. This starter pack helps you set up apps that require flexible environment handling (like Torch/CUDA), with minimal effort.
---
## Prerequisites
* **Python:** A compatible version (defaults to `3.11` in launchers, but can be changed). Ensure it's in your system's PATH.
* **uv:** The Python package manager. Install it if you haven't already:
```bash
pip install uv
# or pipx install uv
```
See the [official uv documentation](https://github.com/astral-sh/uv#installation) for more ways to install.
## 🧰 Features
- Python `3.11` virtual environment with `uv`
- Optional PyTorch installation (auto-matches CUDA version)
- Supports `--dry` or `UV_APP_DRY=1` to skip PyTorch install (good for testing)
- Cross-platform launchers: `.bat`, `.ps1`, `.sh`
- Clean GUI stub using `PySide6` (can be replaced with your own GUI)
- Friendly for beginners and pro devs alike
---
### 🛠 Folder Contents
| File | Purpose |
|-----------------------|---------|
| `main.py` | Launches your GUI app |
| `gui/gui_app.py` | PySide6 GUI logic (`UVAppWindow`) |
| `gui/__init__.py` | Makes `gui` a Python package |
| `install_torch.py` | Smart PyTorch installer (CUDA-aware) |
| `requirements.txt` | Base dependencies (synced by `uv`) |
| `run_uv.bat` | Windows launcher |
| `run_uv.ps1` | PowerShell launcher |
| `run_uv.sh` | Linux/macOS/WSL launcher |
---
### 🚀 Quickstart
🪟 Windows (run_uv.bat)
```bat
:: Optional: Skip torch install (for testing)
set UV_APP_DRY=1
:: Run this script
run_uv.bat
```
💻 PowerShell (run_uv.ps1)
```powershell
$env:UV_APP_DRY=1 # Optional
./run_uv.ps1
```
🐧 Linux/macOS (run_uv.sh)
```bash
export UV_APP_DRY=1 # Optional
chmod +x run_uv.sh
./run_uv.sh
```
---
### ⚙️ Environment Behavior
| Variable / Flag | Effect |
|---------------------|--------|
| `UV_APP_DRY=1` | Skips PyTorch installation |
| `--dry` | Same effect when passed directly to `install_pytorch.py` |
| Python version | Controlled inside the launcher (`python3.11` by default) |
---
### 🧪 Testing (No CUDA/No Torch)
If you're just testing the GUI, set `UV_APP_DRY=1` in your script or terminal. This skips the heavy install step.
---
### 🧠 Ideas for Expansion
- Add translation files or multi-language GUI switching
- Drop in custom GUI logic (e.g. Whisper, TTS, transcription)
- Add `.env` support for dynamic configuration
---
About UV-App-Starter-Pack
This project was created to simplify the often tedious process of setting up a new Python GUI application, especially when targeting multiple operating systems (Windows, macOS, Linux) and dealing with dependencies that require specific system configurations (like PyTorch with different CUDA versions).
**Core Goals:**
* **Rapid Setup:** Use `uv` for near-instantaneous virtual environment creation and dependency installation.
* **Cross-Platform:** Provide ready-to-use launcher scripts (`.bat`, `.ps1`, `.sh`) for a consistent experience everywhere.
* **Dependency Handling:** Demonstrate robust dependency management, including the conditional installation of PyTorch based on detected CUDA capabilities.
* **Clean Foundation:** Offer a minimal PySide6 GUI application stub that is easy to replace or build upon.
Whether you're a beginner looking for an easy entry into GUI development or an experienced developer needing a reliable template for ML/AI or other complex applications, this starter pack aims to get you running faster.