personal-os-setup: a terminal UI for provisioning Windows, Linux, macOS, WSL2, Google TV and Home Assistant

What personal-os-setup actually replaces

The project targets a narrow but common problem: the first day on a new machine. Reinstalling an OS means remembering that Zsh and Oh-My-Zsh need configuring, that WSL2 needs its own setup inside Windows, that GPU drivers are a separate chore from the rest of the package set, that Docker needs a post-install step, and that dotfiles want to be synced through chezmoi. The README describes the project as an "opinionated terminal UI app + documentation hub" covering Windows, Linux, macOS, WSL2, Google TV with Stremio, and Home Assistant on a home server. That is the audience: individual developers and homelab owners who set up their own machines, not platform teams rolling out images. The opinion is baked in. You click through a menu of actions rather than writing your own script, so the value is the curated list of packages and configuration steps, not flexibility. If your setup diverges from the author's, you are editing a fork, and the README's contributing section warns that a fork should stay ahead of upstream and that merging will conflict on most shared files.

How the TUI, installers and auto-update fit together

The architecture is visible in the repository layout. The application is a Python package under src/personal_os_setup, with the entry point declared in pyproject.toml as personal-os-setup = "personal_os_setup.frontend.main:main". The interface is built on Textual, pinned at 8.2.8, with pydantic and pydantic-settings for configuration, PyYAML for data files, and loguru for logging. Two platform installers sit at the repository root: install_unix.sh and install_windows.ps1. Both clone or reuse a checkout, then expose a personal-os-setup command, into ~/.local/bin on Unix and onto the PATH on Windows. The piece worth flagging is the update model. The README states the app "auto-updates on every launch": it runs a git pull on the installed checkout before starting the UI. That makes the installed directory a live git working tree rather than a frozen release, which is convenient for a single user machine and awkward anywhere you care about reproducibility. There is no version pinning at launch, so the code you execute on Monday may differ from Friday's if upstream pushed. The Makefile splits targets across makefiles/ modules for install, run, checks, tests, cleaning, CI, build, VM and skills, which is how the project keeps its own development commands organized.

Installing personal-os-setup and running it the first time

On Linux, WSL2 or macOS the README gives a single command that downloads and runs install_unix.sh. It installs the repository into ~/.personal-os-setup, or reuses and updates that directory if it already exists, and links the personal-os-setup command into ~/.local/bin. If you run the script from inside an existing clone, it updates that checkout in place instead of creating a separate copy.

sh -c "$(wget https://raw.githubusercontent.com/AmineDjeghri/personal-os-setup/main/install_unix.sh -O -)"

After that, the command is on your PATH and you launch the interface from anywhere.

personal-os-setup

On Windows 11 the README instructs you to run one command in PowerShell as administrator. It downloads install_windows.ps1 to a temporary path, then executes it with the execution policy bypassed for that invocation. The script installs into %USERPROFILE%\.personal-os-setup and adds the command to your PATH.

$u='https://raw.githubusercontent.com/AmineDjeghri/personal-os-setup/main/install_windows.ps1'; $p="$env:TEMP\install_windows.ps1"; iwr $u -UseBasicParsing -OutFile $p; powershell -ExecutionPolicy Bypass -File $p

If you would rather edit the code or fork it, the README says to clone instead of using the one-liners, then run ./install_unix.sh from inside the clone, or ./install_windows.ps1 on Windows, or make install-dev followed by make run. Because the app pulls before every launch, expect the first start to touch the network even when you changed nothing.

The Python 3.14 pin and the auto-update trade-off

The hardest constraint is the interpreter. pyproject.toml sets requires-python to >=3.14,<3.15, so the tool runs on Python 3.14 only, not 3.13 and not 3.15. On a distribution whose default python3 is older, the one-liner has to find or install a 3.14 interpreter before anything else works, and the README does not document how the install script resolves that. The second limitation is the update-on-launch behaviour. It means the tool you invoke is whatever upstream main contains at that moment, so a bad commit reaches your machine the next time you open the app. There is no documented rollback, no documented pin to a release tag, and no documented offline mode; the README is silent on all three. If you are provisioning a machine that must stay in a known state, or you work on a network where a git pull at startup is unacceptable, this design is a direct obstacle rather than a detail. The VM targets in the Makefile exist precisely because running the setup against a live machine is risky: the README suggests trying it in a disposable KVM/QEMU/libvirt VM first.

Where a declarative provisioner is the better answer

The obvious alternative is a declarative configuration management tool, and the difference is not cosmetic. personal-os-setup is imperative and interactive: you open a TUI, choose actions, and the app executes them against the current machine. A tool in the Ansible, Nix or chezmoi mould describes the desired end state in files, then converges the machine toward it. That gives you idempotence, a reviewable diff before anything changes, and the same result on the tenth machine as on the first. personal-os-setup does use chezmoi, but only as one action inside its menu, not as the model for the whole tool. The trade-off is real in both directions. Declarative tooling costs you the time to write and maintain the description, and it is poor at the exploratory "what should I install on this new laptop" moment. personal-os-setup is fast to start and gives you a curated menu, but it cannot tell you whether your machine already matches a known state. If you maintain more than a couple of machines, or you need provisioning to run without a person watching, the declarative route wins on the properties that matter.

Licence, maintenance and the cost of staying current

The project is MIT licensed, which permits commercial and private use, modification and redistribution provided the copyright notice and permission notice are retained. That is a permissive licence, but it says nothing about the packages the TUI installs: those carry their own licences, and the MIT grant on this repository does not extend to them. The repository is not archived, and the last push was on 2026-09-09, with releases v2.14.0 on 2026-09-08, v2.13.2 on 2026-09-07 and v2.13.1 on 2026-09-07. Version numbers come from python-semantic-release in the dev dependency group, so releases are automated. The upgrade cost is unusual: because the app pulls on every launch, there is no upgrade step to perform, and equally no moment where you decide to take a new version. Your exposure to upstream changes is continuous. For a solo machine that is the point of the design; for anything shared it means the installed checkout is a moving target, and the README does not describe a way to freeze it.

Editorial conclusion

Adopt personal-os-setup if you set up machines by hand, want a guided TUI for Zsh, dotfiles, WSL2, GPU drivers and Docker post-install, and are comfortable with the app running a git pull on the installed checkout at every launch. Skip it if you need unattended, idempotent provisioning across a fleet, or if you cannot run Python 3.14, which pyproject.toml pins as the only supported interpreter range. Before running it on a daily driver, use the make vm-cachyos, make vm-ubuntu-server or make vm-ubuntu targets the README points to, and read docs/linux/CachyOS.md for the full VM command list.

Frequently asked questions

Official sources

1. AmineDjeghri/personal-os-setup on GitHub
2. License: MIT
3. Project website
4. README
5. Releases