The most common question from experienced Linux users considering Shani OS is: "I know how to manage a system with pacman/apt/dnf. What do I actually do differently here?"
The honest answer is: not much changes in daily use. You still install apps, manage services, configure your system, and run development tools. The difference is that each category of software has a specific layer it belongs to — and once you understand the three-layer model, the new habits are straightforward.
This guide is a direct translation guide. Every traditional workflow maps to a Shani OS equivalent. Full reference: docs.shani.dev.
---
The Mental Model Shift
On a traditional Linux distribution, software installation means writing files into the OS root. The package manager is the single source of truth for what is installed. You manage everything — system libraries, GUI apps, CLI tools, development runtimes — through the same tool.
On Shani OS, the OS root is frozen. It is a verified, signed image. You do not write into it because doing so would undermine the entire reliability guarantee: if you can add arbitrary packages to the OS, the OS is no longer the reproducible artefact that the update pipeline verified.
Instead, persistent layers sit alongside the OS, each in its own Btrfs subvolume:
@flatpak— GUI desktop applications (browsers, office, media, etc.)@snapd— Snap packages when an app is only available on the Snap Store@nix— CLI tools, development runtimes, and language toolchains@containers— Distrobox and Podman OCI containers@machines— systemd-nspawn system containers@lxc/@lxd— LXC/LXD full system containers@libvirt/@qemu— Virtual machine disk images@waydroid— Android environment
All survive every OS update and rollback. They are never touched by shani-deploy. They have their own update paths. They do not conflict with each other.
---
Package Installation: The Full Translation Table
GUI Applications
| Traditional | Shani OS | |---|---| | sudo apt install firefox | flatpak install flathub org.mozilla.firefox | | sudo dnf install gimp | flatpak install flathub org.gimp.GIMP | | sudo pacman -S vlc | flatpak install flathub org.videolan.VLC | | yay -S spotify | flatpak install flathub com.spotify.Client | | sudo apt install code | flatpak install flathub com.visualstudio.code |
Search for the Flatpak app ID at flathub.org or via flatpak search <n>. Most major GUI applications are on Flathub. If an app is only available on the Snap Store, snap install <n> works as a fallback — Snap is pre-configured on Shani OS and the @snapd subvolume persists across updates just like @flatpak.
Windows Applications
Windows .exe software runs through Wine — a compatibility layer that translates Windows API calls to Linux equivalents. No Windows licence required, no VM overhead for most apps.
| Traditional | Shani OS | |---|---| | Run a Windows .exe installer | Open with Bottles — creates an isolated Wine environment | | Install a Windows productivity tool | Bottles → Create bottle → Run Executable | | Run legacy Windows software | Bottles with Wine Staging or Wine-GE runner | | Windows game (non-Steam) | Bottles with Wine-GE, or Heroic Games Launcher |
Bottles (com.usebottles.bottles) is pre-installed on the KDE Plasma edition and available on Flathub for the GNOME edition. It manages isolated Wine prefixes per application, handles runtime dependencies (Visual C++, .NET, DirectX) via its built-in dependency installer, and supports multiple Wine runners including Wine-GE and Proton-GE.
For applications that require a real Windows kernel — hardware drivers, anti-cheat systems, enterprise software with kernel-level components — a Windows VM via virt-manager (pre-installed on KDE Plasma) or GNOME Boxes is the reliable path. VM disk images live in @libvirt, completely independent of the OS. Guide: Windows Apps on Shani OS · Virtual Machines on Shani OS.
For portable self-contained tools distributed as AppImages, download the .AppImage, make it executable, and run — or open with Gear Lever (pre-installed) to add it permanently to your launcher with automatic update checking.
CLI Tools and Development Runtimes
| Traditional | Shani OS | |---|---| | sudo apt install nodejs | nix-env -iA nixpkgs.nodejs | | sudo pacman -S python | nix-env -iA nixpkgs.python312 | | sudo dnf install rustup | nix-env -iA nixpkgs.rustup | | sudo apt install ripgrep | nix-env -iA nixpkgs.ripgrep | | sudo pacman -S kubectl | nix-env -iA nixpkgs.kubectl | | brew install bat | nix-env -iA nixpkgs.bat | | sudo apt install golang | nix-env -iA nixpkgs.go | | sudo pacman -S neovim | nix-env -iA nixpkgs.neovim |
Before using Nix, add a channel once:
nix-channel --add https://nixos.org/channels/nixpkgs-unstable nixpkgs
nix-channel --updateThen install anything from the 100,000+ packages at search.nixos.org:
nix-env -iA nixpkgs.package-nameSystem-Level Software (Not Available)
Some categories of software cannot be installed into the OS root and must use alternatives:
| Traditional | Shani OS Alternative | |---|---| | sudo pacman -S nvidia | Drivers are part of the OS image; already configured at install | | sudo apt install linux-headers | Kernel headers are in the OS image | | Kernel modules via DKMS | Custom modules are not supported; use upstream drivers | | sudo apt install docker | Use Podman (pre-installed, Docker-compatible) |
This is a short list. Most software that experienced Linux users install falls into the GUI apps or CLI tools categories above, both of which have direct equivalents.
---
System Management
System Updates
| Traditional | Shani OS | |---|---| | sudo apt upgrade | sudo shani-deploy | | sudo pacman -Syu | sudo shani-deploy | | sudo dnf upgrade | sudo shani-deploy | | Reboot to apply kernel | Reboot after shani-deploy | | Roll back to previous packages | sudo shani-deploy -r (entire OS, instant) |
The critical difference: shani-deploy replaces the entire OS image, not individual packages. There is no "partial update" state. Either the update applies fully and cleanly, or it does not apply at all. And if the new image causes problems, rollback takes you back to the previous complete OS state — not a partial undo.
Service Management
Service management with systemctl works identically:
# All standard systemctl commands work
sudo systemctl enable sshd
sudo systemctl start nginx
sudo systemctl status nginx
sudo systemctl restart NetworkManager
# Enabling services persists via the /etc OverlayFS
# Your enabled services survive OS updatesConfiguration Files
Editing /etc files works exactly as expected. Changes are stored in the OverlayFS upper layer (@data) and persist across every OS update and rollback:
# Edit any /etc file normally
sudo nano /etc/ssh/sshd_config
sudo nano /etc/hostname
sudo nano /etc/hosts
# Changes to /etc persist — they are yours across updatesTo see what you have customised (what differs from the OS defaults):
ls /data/overlay/etc/upper/If an /etc change causes a problem, you can revert a specific file to the OS default:
sudo rm /data/overlay/etc/upper/path/to/file
# The OS default (lower OverlayFS layer) becomes active again---
Development Workflows
Multiple Versions of the Same Tool
One of the most common pain points on traditional distributions: needing Node 18 for one project and Node 22 for another. Package managers typically only have one version of a tool installed at a time.
Nix solves this cleanly:
# Install both versions simultaneously — no conflict
nix-env -iA nixpkgs.nodejs_18
nix-env -iA nixpkgs.nodejs_22
# Per-project shell with a specific version (does not install globally)
nix-shell -p nodejs_18 # enters a shell with Node 18 on PATH
nix-shell -p nodejs_22 # separate shell with Node 22
# Reproducible project environment via shell.nix
# Place in project root — everyone running nix-shell gets identical toolsFull Nix guide: Nix on Shani OS.
Full System Containers (LXC/LXD and systemd-nspawn)
For workflows that need a complete isolated Linux system — with its own init, services, and network stack, lighter than a full VM — two options are pre-installed:
LXC/LXD is the more full-featured option, with a built-in image catalog, port forwarding, and snapshot management. Container storage lives in @lxc/@lxd:
lxc launch ubuntu:24.04 myserver
lxc exec myserver -- bashsystemd-nspawn is the lightest option — no daemon, no image format, just point it at a Linux root directory and it boots. Container filesystems live in @machines:
sudo machinectl pull-tar --verify=no \
https://geo.mirror.pkgbuild.com/images/latest/Arch-Linux-x86_64-basic.tar.zst archlinux
sudo machinectl start archlinux
sudo machinectl login archlinuxAndroid Apps and Development
Waydroid runs a full hardware-accelerated Android stack in a container. Indian apps (BHIM, DigiLocker, IRCTC), streaming apps, and Android development testing all work without a separate device. The @waydroid subvolume persists across every OS update:
sudo waydroid init # one-time setup
waydroid session start
waydroid show-full-ui
waydroid app install myapp.apk # test your APK with adbGuide: Waydroid on Shani OS.
The AUR is not directly available on Shani OS — but the full Arch Linux experience, including yay and the AUR, is one command away via Distrobox:
# Create a full Arch Linux container with AUR access
distrobox create --name arch --image archlinux:latest
distrobox enter arch
# Inside: full pacman, yay, makepkg — everything works
yay -S some-aur-package
# Export a binary to your host desktop
distrobox-export --bin /usr/bin/some-toolExported binaries from Distrobox containers appear in your host PATH and app launcher. BoxBuddy (pre-installed) gives you a graphical interface for creating and entering containers.
PPAs and Third-Party Repos (Ubuntu Users)
Third-party APT repos and PPAs are not available for the host OS, but the same approach works inside a Distrobox Ubuntu container:
distrobox create --name ubuntu-dev --image ubuntu:24.04
distrobox enter ubuntu-dev
# Inside: standard apt, add-apt-repository, PPAs — all work
sudo add-apt-repository ppa:some/ppa
sudo apt install some-package
distrobox-export --bin /usr/bin/some-package---
Filesystem Layout: What Changed
The parts of the filesystem you regularly interact with are the same. The OS root directories have different behaviour:
| Directory | Behaviour | |---|---| | /home | Fully writable, stored in @home — unchanged from any Linux distro | | /etc | Writable via OverlayFS — your changes persist | | /tmp | Writable tmpfs — cleared on reboot as usual | | /usr | Read-only — OS files live here, you cannot modify them | | /bin, /lib, /sbin | Symlinks into /usr — effectively read-only | | /var | tmpfs — cleared on reboot; persistent state bind-mounted from @data | | /nix | Writable by Nix — your Nix packages live here (@nix) | | /var/lib/flatpak | Flatpak apps — writable via @flatpak | | /var/lib/snapd | Snap packages — writable via @snapd | | /var/lib/containers | Distrobox and Podman containers — writable via @containers | | /var/lib/machines | systemd-nspawn system containers — writable via @machines | | /var/lib/lxd | LXD containers — writable via @lxd | | /var/lib/libvirt | VM disk images — writable via @libvirt | | /var/lib/waydroid | Android environment — writable via @waydroid |
The read-only nature of /usr is the main thing to internalise. Anything that tries to write to /usr/local/bin or install files into /usr/share will fail. Use Nix, Flatpak, Snap, or Distrobox instead.
---
Shell and Terminal Experience
The shell environment is configured out of the box with the tools experienced Linux users expect:
# Already installed and configured
echo $SHELL # /usr/bin/zsh
which starship # /usr/bin/starship (prompt)
which fzf # /usr/bin/fzf (fuzzy finder)
which bat # already in PATH (Nix or system)
which eza # modern ls replacement
# McFly for smart command history (replaces Ctrl+R)
# Already integrated into the shell configYour .zshrc and .bashrc in $HOME work exactly as expected. Shell configuration is in your home directory (@home), completely independent of the OS.
---
Backup and Data Management
Before migrating, back up your existing system's data. After migrating, your home directory is your primary concern — the OS can always be reinstalled or rolled back, but your data lives in @home.
# restic is pre-installed — encrypted, versioned backups
restic -r s3:s3.amazonaws.com/mybucket init
restic -r s3:s3.amazonaws.com/mybucket backup ~/Documents ~/Projects ~/Pictures
# rclone is pre-installed — sync to cloud storage
rclone config # set up Google Drive, S3, Backblaze, etc.
rclone sync ~/Documents gdrive:Backup/DocumentsBoth restic and rclone configurations persist in /data/varlib/ and survive OS updates.
---
The Things That Just Work
These do not require any migration thought — they work on Shani OS exactly as they do on any Linux distribution:
- SSH, GPG keys, and credential management (stored in
~/.sshand~/.gnupg) - Docker Compose workflows (use
podman composeorpodman-dockerdrop-in) - Git repositories and configuration
- Terminal emulators, Tmux, and screen sessions
- Python virtual environments in
~/.venvor project directories - Node projects in
~/projectswithnode_modules - Dotfiles managed by
stow,chezmoi, or a bare git repo - Any tool or script that lives in your home directory
---
Resources
- The Shani OS Software Ecosystem — canonical "what to use when" guide with decision flowchart and comparison table
- docs.shani.dev — migration reference and key concepts
- Shani OS FAQ — common questions including rollback, file safety, and dual boot
- Nix on Shani OS — detailed Nix workflow guide
- Flatpak on Shani OS — full Flatpak guide
- Distrobox on Shani OS — full Distrobox guide (AUR, apt, PPAs)
- Windows Apps on Shani OS — Wine, Bottles, and when to use a VM
- Waydroid on Shani OS — Android apps
- Shani OS Troubleshooting Guide — when things go wrong
- Telegram community — ask migration questions
Download Shani OS at shani.dev →
---
Built in India 🇮🇳 · Immutable · Atomic · Zero Telemetry