nami alpha Docs

Install nami

Put nami on the distribution you already have, keep it up to date, and take it off again.

Install nami

Run the installer in a terminal on Ubuntu, Fedora, Mint, Arch or any other distribution on x86_64. It asks for your password once and takes a minute or two.

curl -fsSL https://namios.dev/install | sh

Open a new terminal and try nami install firefox. Log out and back in once, so your app menu finds nami’s apps. Then go on to Your first apps.

The installer checks the release against its signed checksums. If a check fails, nothing is installed.

nami is alpha software: most things work, some may not yet, and you can undo every change. If something isn’t working, run nami report.

Set up from your config repo

If you keep your nami files in a config repo, the installer can apply it right away.

curl -fsSL https://namios.dev/install | sh -s -- --config github:ada/nami-config

--config takes what nami apply takes: github:ada/nami-config, github:ada/nami-config@branch, or any git URL. If that step fails, nami stays installed and you can run nami apply later.

Read the script first

You can download the installer and look at it before you run it.

curl -fsSL https://namios.dev/install -o install-nami.sh
less install-nami.sh
sh install-nami.sh

Install another way

WayHow
.deb or .rpmDownload it from Download, when the release has one, and open it. Removing the package removes nami.
Offlinesudo sh nami-<version>-x86_64-linux.run. Apps still download, so installing them needs a network.
NixOSThe same one-line installer, or import the release’s nixos/nami.nix and run sudo nixos-rebuild switch.
From source./build.sh, sudo ./install.sh, then sudo nami update --from <catalog> --unsigned for a catalog you built.

On NixOS, nothing in your configuration changes and no rebuild is needed. nami shares the Nix store, and nix-collect-garbage leaves nami’s apps alone.

Complete commands with Tab

Press Tab while you type a nami command, and your shell shows what fits: commands, options, apps from the catalog, an app’s versions, your project’s tasks and services, the changes you can undo, and the keys in your nami file. zsh and fish show what each one is.

$ nami install fire<Tab>
firefox      -- Browse the web
firefox-esr  -- Browse the web, supported longer
...
$ nami install firefox@<Tab>
firefox@160  -- 160.0, since Nov 12, 2026
firefox@159  -- 159.0.2, Oct 1 – Nov 12, 2026

The installer sets it up for bash, zsh and fish, if you have them. Open a new terminal after you install. In bash it needs the bash-completion package, and in zsh it needs compinit in your ~/.zshrc, which most setups already have. On namiOS it works out of the box.

If you keep your own shell files, load it there instead:

eval "$(nami completions bash)"     # in ~/.bashrc
eval "$(nami completions zsh)"      # in ~/.zshrc, after compinit
nami completions fish | source      # in ~/.config/fish/config.fish

Know who can change what

nami uses your distribution’s admin group: anyone in wheel, sudo or admin is an admin.

nami install vlc                   # anyone: just for you, in ~/user.nami
nami install --for-everyone vlc    # admins: for everyone, in /etc/nami/computer.nami
nami status                        # says which you are

Admins never type sudo nami. A small service, nami-daemon, makes the change as root after checking who’s asking.

Check what it needs

nami is tested on Ubuntu, Debian, Fedora, Arch, openSUSE, Alpine and Void, and runs on NixOS. It needs an x86_64 processor, curl or wget, and sudo once. Services in your files need systemd; on Alpine or Void, apps and files work.

Everything nami installs lives under /nix. On a read-only system like Fedora Silverblue or SteamOS, the installer mounts /var/lib/nami/nix on /nix. Every path nami touches is in Files on disk.

Update nami

nami updates itself once a day, with the apps in /etc/nami/computer.nami, and says so in a notification. It checks each new release’s signature before it installs it. Your files stay as they are.

To update now, open nami and click Updates, then Update Now. Or run:

nami self-update            # nami alone; an admin, no sudo needed
sudo nami self-update       # anyone else
nami self-update --check    # only say whether there's a newer version

To update only when you ask, turn off Install updates automatically in Updates, or add one line to computer.nami:

/etc/nami/computer.nami
packages:  - vlcupdates: manual

To update your own apps, see Update your apps.

Bring your Nix setup

nami installs from nixpkgs and the same binary cache as Nix, so the packages are the same. You describe them in YAML instead of the Nix language.

nami import ~/.config/home-manager/home.nix
~/user.nami
packages:  - firefox  - ripgrep  - git:      ~/.gitconfig:        user:          name: Ada          email: ada@example.orgenv:  EDITOR: nvim# Not converted from home.nix (nami import):#   xdg.mimeApps: no nami equivalent
nami import .                                    # a flake's dev shell or shell.nix → project.nami
sudo nami import /etc/nixos/configuration.nix    # NixOS → /etc/nami/computer.nami
nami import ~/dotfiles --to user --dry-run       # show what it would write

Import merges into the file and applies nothing, so run nami apply next. What has no nami equivalent, like overlays or the bootloader, is listed at the end of the file. If you’re leaving home-manager, remove it and switch first, so its links in your home go away.

Nixnami
configuration.nix, home-managercomputer.nami, ~/user.nami
a flake’s dev shell, flake.lockproject.nami, nami.lock
nixos-rebuild switch, home-manager switchnami apply
nix develop, direnv’s use flakenami shell, nami hook
generations, --rollbacknami history, nami undo
overrideAttrs, stdenv.mkDerivationextends:, a recipe
environment.etc, home.file, dconf.settingsfiles:, settings:

nami and an installed Nix share one /nix/store. Set NAMI_NIX=off to make nami ignore Nix.

Remove nami

The uninstaller takes out the daemon, nami’s packages and the files the installer added.

sudo sh /nix/var/nami/uninstall.sh

If you installed the .deb or .rpm, remove the package instead. Your nami files stay, in /etc/nami, ~/user.nami and ~/.config/nami. Services and /etc files that nami apply set up stay too, so take them out of your files and apply before you uninstall.

Something wrong or missing here? nami report tells us, or Report a problem in the nami window.