https://github.com/bunhine0452/uvws
Manage and run all your uv-based Python projects from one place — with one-click execution, a built-in terminal, port force-kill, and Git integration. Available on macOS and Windows.
https://github.com/bunhine0452/uvws
astral-uv desktop-app developer-tools devtools macos project-manager python python-development react rust tauri uv virtualenv windows
Last synced: 5 days ago
JSON representation
Manage and run all your uv-based Python projects from one place — with one-click execution, a built-in terminal, port force-kill, and Git integration. Available on macOS and Windows.
- Host: GitHub
- URL: https://github.com/bunhine0452/uvws
- Owner: bunhine0452
- License: mit
- Created: 2026-05-29T07:25:54.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-06-16T13:20:27.000Z (13 days ago)
- Last Synced: 2026-06-16T13:27:20.031Z (13 days ago)
- Topics: astral-uv, desktop-app, developer-tools, devtools, macos, project-manager, python, python-development, react, rust, tauri, uv, virtualenv, windows
- Language: TypeScript
- Homepage: https://uvws.site
- Size: 7.97 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
uvws
A desktop app to manage all your Python projects in one place — powered by uv
English · 한국어
---
When you have several Python projects, typing `cd`, then `source .venv/bin/activate`, then `python main.py` every single time starts to wear thin. uvws shrinks that whole dance down to a single click.
---
## Download
Grab it from [**uvws.site**](https://uvws.site) or the [**Releases page**](https://github.com/bunhine0452/uvws/releases).
| Platform | File |
|---|---|
| macOS Apple Silicon (M1–M4) | `uvws_x.x.x_aarch64.dmg` |
| macOS Intel | `uvws_x.x.x_x64.dmg` |
| Windows 10+ | `uvws_x.x.x_x64-setup.exe` |
**Prerequisite:** [uv](https://docs.astral.sh/uv/getting-started/installation/) must be installed.
```bash
# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```
### Security warning on first launch (macOS)
Because the app isn't Apple-notarized, macOS may show a warning.
- **"App is damaged" error**: run `xattr -cr /Applications/uvws.app` in the terminal, then try again
- **Generic warning**: right-click the app → Open → confirm Open
You only need to do this once; it launches normally afterward.
---
## Features
**Register & run projects**
Register a folder once and launch it with a single click from then on. Runs are wrapped in `uv run`, so they work without activating a virtualenv — and if there's no `.venv`, one is created automatically on first run.
**Import wizard**
When importing a folder that has a `requirements.txt` or `pyproject.toml`, pick a Python version (3.10–3.13) and install dependencies in one step.
**Built-in terminal**
Each project's stdout/stderr streams live into an xterm.js terminal. When a `localhost:XXXX` address is detected in the logs, an "Open in browser" button appears automatically.
**Port management (force-kill)**
Force-kills (SIGKILL) whatever process is holding a given port, retrying and verifying until the port is actually free — so you never have to type `lsof -i` for a "port already in use" error again.
**Concurrent runs & auto-cleanup**
Spin up multiple localhost servers at once, each managed with its own terminal and port. Quitting the app shuts down every running server, and any orphans left by a crash are swept on the next launch.
**Git integration**
If a project folder is a Git repository, see its branch, ahead/behind counts, changed-file count, and latest commit at a glance — and run Fetch / Pull / Push with a single button.
**Dependency viewer**
Inspect the packages and versions installed in `.venv`, and use the Sync button to reinstall against `requirements.txt` / `pyproject.toml`.
**Korean / English**
Switch the language instantly from the About screen.
---
## Build from source
```bash
git clone https://github.com/bunhine0452/uvws.git
cd uvws
pnpm install
pnpm tauri dev # development mode
pnpm tauri build # release build
```
Build artifacts are produced in `src-tauri/target/release/bundle/`.
**Requirements:** Node.js 18+, pnpm, Rust stable, uv, [Tauri prerequisites](https://v2.tauri.app/start/prerequisites/)
---
## Roadmap
- [x] Register / configure / delete projects
- [x] One-click run via `uv run`
- [x] Live xterm.js terminal
- [x] Port auto-detection & open-in-browser
- [x] Kill Port
- [x] Import wizard (with Python version selection)
- [x] Dependency viewer & Sync
- [x] Concurrent runs & auto server cleanup on app quit
- [x] Git integration (status, fetch, pull, push)
- [x] Localization (Korean / English)
- [ ] Plugin system
- [ ] Docker container management
---
## Contributing
PRs and issues are both welcome. For bug reports or feature ideas, open an [Issue](https://github.com/bunhine0452/uvws/issues).
---
## License
[MIT License](LICENSE)