The Problem
Setting up a new machine is slow and error-prone. Every OS has its own package managers, terminal configurations, and driver quirks. Reproducing a consistent development environment across Windows, WSL2, Linux, and macOS typically means maintaining separate setup scripts and documentation that drift out of sync.
What This Does
awesome-os-setup is a cross-platform setup toolkit with two layers. The first is a Python TUI (src/awesomeos/frontend/main.py) built on TermTk that detects your OS (src/awesomeos/detectos.py) and presents package installation and system configuration tasks. The second is a set of one-liner installers (installwindows.ps1, installunix.sh) that bootstrap the environment before the TUI runs.
The package catalog lives in src/awesomeos/config/packages.yaml. Concrete backend managers handle each platform: windowswinget.py, darwinbrew.py, ubuntuapt.py, ubuntusnap.py, and archyay.py. WSL-specific workflows (distro list, export, import, move, unregister) are in src/awesomeos/tasks/system/windowswsltasks.py. The repo also ships curated configs for GlazeWM, Windows Terminal, Zsh, and Powerlevel10k under src/awesomeos/config/.
How To Use It
Setup: The README documents one-liner installers. For Linux/WSL2/macOS:
sh -c "$(wget https://raw.githubusercontent.com/AmineDjeghri/awesome-os-setup/main/installunix.sh -O -)"
For Windows 11 (PowerShell as administrator):
iex ((New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/AmineDjeghri/awesome-os-setup/main/installwindows.ps1'))
Configuration: Package lists are defined in src/awesomeos/config/packages.yaml. Environment variables go in .env.example (copy to .env). The project uses uv for dependency management — uv.lock is present, so uv sync reproduces the environment exactly.
Running it: After the installer runs, the TUI is the entry point. The Python app lives in src/awesomeos/frontend/main.py. The Makefile and makefiles/ directory define standard targets (make dev, make test, make install).
Real-World Use
A developer with a Windows 11 primary machine and an Ubuntu server can use the PowerShell installer to enable WSL, install Windows Terminal with consistent fonts and color schemes, and configure GlazeWM for tiling. The same packages.yaml catalog drives package selection on both platforms — on Windows via winget, on Ubuntu via apt and snap. The WSL task module handles exporting and re-importing a distro when migrating to new hardware.
Code Health & Issues
Med – No lockfile for reproducibility: pyproject.toml declares dependencies but no constraint pins are visible; the uv.lock file mitigates this if you use uv sync. Low – Dependabot is configured: .github/dependabot.yml exists, which is good hygiene. Med – CI is present but not exhaustive: GitHub Actions workflows cover build, docs, pre-commit, and tests (.github/workflows/), but only 5 test files exist — coverage is thin for a cross-platform tool. Low – Large binary/config blobs in repo: src/awesomeos/config/windows/Files_3.0.15.0.zip and .reg files inflate the repo and complicate review. Low – Heuristic risk: The analysis detected Django/Docker references, but no Django settings or Dockerfile beyond tests/archlinux/Dockerfile. Likely false positives.
The Bottom Line
This is a well-organized, genuinely useful personal setup toolkit that has been cleaned up and generalized from a popular 600-star original. The cross-platform abstraction is the strongest part — the package manager backends are cleanly separated. It is best suited to individual developers or small teams who want a reproducible desktop setup without adopting a heavyweight tool like Ansible. The main weaknesses are thin test coverage and the TUI's niche appeal; if you prefer declarative config files over interactive menus, this may not fit your workflow.