# Install and update niv

`niv` is one file. It runs on macOS (Apple silicon and Intel), Linux (x86-64 and arm64) and Windows (x86-64).

## Install

- **macOS**, with Homebrew: `brew install niv-md/tap/niv`
- **Linux**: `curl -fsSL https://releases.niv.md/install.sh | sh`
- **Windows**, in PowerShell: `irm https://releases.niv.md/install.ps1 | iex`

The Linux script puts `niv` in `~/.local/bin`, and the Windows one in `%LOCALAPPDATA%\niv\bin`, which it adds to your PATH. Both check the download, and install nothing if the check fails. Nothing runs as administrator.

- `NIV_INSTALL_DIR=<folder>` installs somewhere else.
- `NIV_VERSION=<version>` installs that version instead of the newest.

On macOS the script doesn't install: it points to Homebrew.

Check it with `niv --version`.

## Update

- **macOS**: `brew upgrade niv`.
- **Linux and Windows**: `niv upgrade`, or run the install line again.

Restart any running `niv sync` afterwards: the one that's running is still the old version.

## niv upgrade

```
niv upgrade [--json]
```

Downloads the newest niv from releases.niv.md and puts it in place of this one. It checks the version list's signature and the download's checksum first; if either check fails, nothing changes.

```
$ niv upgrade
niv 0.2.21 is the newest version.
```

```
{"v":1,"time":"2026-10-29T19:02:58.423Z","type":"upgrade","state":"newest","from":"0.2.21","message":"niv 0.2.21 is the newest version."}
```

When there's a newer one, it says "Downloading niv 0.2.22 (you have 0.2.21)…" and then "Installed niv 0.2.22. Restart any running niv sync to use it." In JSON that's `"state":"installed"`, with `from` and `to`. Both exit with 0.

niv 0.2.20 and older can't update themselves: run the install line once, and `niv upgrade` works from then on.

| `state` or `code`                | When                                                                                                                                                                                               | Exit |
| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---- |
| `newest`                         | This is the newest version                                                                                                                                                                         | 0    |
| `installed`                      | It updated                                                                                                                                                                                         | 0    |
| `homebrew`                       | Installed with Homebrew: "Run brew upgrade niv to update it."                                                                                                                                      | 6    |
| `unavailable`                    | This copy can't update itself: an older niv, a copy not installed from releases.niv.md, or no build for this computer. It prints the install line (`install` in JSON) or the releases page (`url`) | 1    |
| `signature`, `stale`, `checksum` | The version list failed its signature check or is out of date, or the download didn't match its checksum. Nothing changed                                                                          | 1    |
| `write-denied`                   | niv can't replace its own file: run it as a user who can write there, or run the install line again                                                                                                | 1    |
| `offline`                        | releases.niv.md didn't answer                                                                                                                                                                      | 5    |

The first four are `upgrade` objects; the others are errors. See [Exit codes](/p/docs/exit-codes).

---

Published with [Niv](https://niv.md/) in the Space Docs.
