nami alpha Docs

Your first apps

Find, install, update and remove apps with nami, next to your distribution's own.

Install an app

nami installs apps from nixpkgs, over 140,000 packages, most of them ready-built, next to apt or dnf.

nami install firefox
Downloaded 297 packages · 1.5 GB
✓ Installed firefox 160.0 · in your user.nami · 2.3 GB more on disk · opens from the launcher
  Undo with nami undo
~/user.nami
packages:  - firefox

Firefox is in your app menu right away, and with your file, the same apps come back on another computer. Each app brings its own libraries, so it never clashes with your distribution’s.

Find an app

Search works offline, from the catalog on your computer. A ✓ marks what you have.

nami search photo
  gimp        3.2.6   GNU Image Manipulation Program
✓ photoflare  1.6.13  Simple but powerful Cross Platform Image Editor

nami install gimp · nami info gimp
100 command-line tools and libraries too: nami search --all photo

Search shows apps first, and tools and libraries when no app matches or with --all. nami update --refresh gets the newest catalog.

nami info tells you what an app is, whether you have it, and how many versions there are.

nami info firefox
firefox 160.0
Fast, Private & Safe Web Browser
MPL-2.0 · http://www.mozilla.com/en-US/firefox/
App · opens from the launcher

Not installed · nami install firefox
314 earlier versions, back to 2016 · nami versions firefox
nami search --category games   # office, graphics, audio-video, games, internet, coding…
nami info firefox --all        # all of its description, and its screenshots
nami list                      # what you have

Install several, or remove one

nami install vlc gimp ripgrep
~/user.nami
packages:  - firefox  - vlc  - gimp  - ripgrep
nami remove vlc
~/user.nami
packages:  - firefox  - vlc  - gimp  - ripgrep

Removing an app takes its settings out of your file too.

If an install fails, nami puts your file back as it was. The nami app does the same on its Discover and Installed pages.

Install for everyone

An admin can install an app for everyone on the computer, without sudo.

nami install --for-everyone vlc
/etc/nami/computer.nami
packages:  - vlc

Packages that set up the computer, like docker or tailscale, always go in that file. See computer.nami.

Pin a version

In your file, a name alone means the newest version. Add a version to stay on one.

~/user.nami
packages:  - ripgrep            # the newest  - firefox: 150       # the newest 150.x  - python3: 3.12.4    # exactly this  - nodejs: 20         # the newest 20.x

nami also looks in earlier nixpkgs releases, so old versions are ready-built too. nami versions lists them, newest first, with when each was current.

nami versions firefox
firefox 315 versions, back to 2016

  160  160.0    since Nov 12, 2026     current
  159  159.0.1  Oct 28 – Nov 12, 2026  ✓ installed
  158  158.0.1  Oct 13 – Oct 28, 2026
  157  157.0.1  Sep 29 – Oct 13, 2026
  …

Pick one: nami install firefox@159, or in a nami file: firefox: 159

nami versions python3 groups by minor version (3.13, 3.12), and --all lists every release. nami search firefox@150 says whether there’s a firefox 150 and how to install it. The version is read as you wrote it, so 3.10 stays 3.10.

Edit the file, then apply

You can edit ~/user.nami in any editor and make the computer match it.

nami apply --dry-run   # show what would change
nami apply
nami undo              # go back to the change before

Every apply is a change you can undo. More in Changes and undo.

Update your apps

nami doesn’t update your apps on its own. When you want newer versions:

nami update --refresh       # get the newest catalog
nami upgrade --dry-run      # see what would get newer
nami upgrade

Pinned versions stay within what you picked, and nami undo takes an upgrade back. To update nami itself, see Update nami.

Install an app from Flathub

Some developers publish their apps on Flathub. Install one by its ID.

nami search --flathub calculator
nami install flathub:org.gnome.Calculator
~/user.nami
packages:  - firefox  - flathub:org.gnome.Calculator

Flathub apps need your distribution’s flatpak package, and they’re always just for you. nami upgrade updates them too.

Install an app made with nami bundle

Some developers publish their app as one file made with nami bundle. Install it from where they publish it, or open a download of it.

nami install bundle:github:ada/myapp
nami install ./myapp-x86_64
~/user.nami
packages:  - firefox  - bundle:github:ada/myapp: { key: 3F2A 9C01 5B7E 22D4 8A10 C3F9 0E6B 7D21 }

key: is the key its developer signs it with, written the first time. On another computer, nami apply downloads the app and installs it only if it’s signed with that key. The app updates itself, and it’s just for you. Installing or removing it is a change like any other, so nami undo takes it back.

Allow or refuse apps that aren’t free

Steam, Spotify, VS Code and other apps that aren’t free software are allowed unless you say otherwise.

~/user.nami
unfree: false     # refuse apps that aren't free softwarepackages:  - firefox

These apps aren’t in the public binary cache, so nami builds them on your computer, which takes a few minutes the first time. You can share the build with your other computers.

When an app isn’t in the catalog

If nixpkgs renamed or dropped a package, nami apply leaves it out, says so, and sets up the rest.

user.nami: leaving out oldtool: it isn't in the catalog (did you mean `newtool`?)

For an app nixpkgs doesn’t have, write your own package. For apps that come only as a .deb or a download, see Apps from other distributions.

When a graphical app shows nothing

The first time you install an app that uses the graphics card, nami also sets up drivers, fonts and languages for it. If an app shows nothing or complains about OpenGL, run nami doctor.

nami doctor

See Troubleshooting for the rest.

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