> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sifr.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Install the Sifr Compiler on macOS or Linux — Quick Start

> Install the Sifr compiler on macOS or Linux using the official installer script, with options for channels, version pinning, and custom directories.

The official Sifr installer is a shell script that downloads a prebuilt binary for your platform, verifies its SHA-256 checksum, installs the `sifr` executable to `~/.sifr/bin/sifr`, and updates your shell profile so new shells can find it. No package manager or build toolchain is required to get started.

## Supported platforms

Sifr stable provides prebuilt binaries for the following targets:

* `aarch64-apple-darwin` (Apple Silicon Mac, macOS 15.0 or newer)
* `x86_64-apple-darwin` (Intel Mac, macOS 15.0 or newer)
* `aarch64-unknown-linux-gnu` (Linux ARM64, glibc 2.39 or newer)
* `x86_64-unknown-linux-gnu` (Linux x86-64, glibc 2.39 or newer)

<Note>
  Windows standalone installation and package-manager distribution are not
  part of the current stable release.
</Note>

## Install Sifr

<Steps>
  <Step title="Run the installer">
    Paste the command below into your terminal. The installer detects your platform automatically and fetches the correct binary.

    <CodeGroup>
      ```bash Stable (recommended) theme={null}
      curl -fsSL https://sifr.sh/install | sh
      ```

      ```bash Stable (explicit) theme={null}
      curl -fsSL https://sifr.sh/install/stable | sh
      ```
    </CodeGroup>

    Stable is the recommended channel. Both commands resolve the active stable
    version from Sifr's governed schema-v2 release index, verify the immutable
    installer digest, and download the matching target artifact.
  </Step>

  <Step title="Reload your shell">
    The installer updates your shell profile (`~/.bashrc`, `~/.zshrc`, or equivalent), but the change only takes effect in new shell sessions. Reload your profile now so the current session can find `sifr`:

    ```bash theme={null}
    source ~/.bashrc   # or ~/.zshrc, ~/.profile — whichever your shell uses
    ```
  </Step>

  <Step title="Verify the installation">
    Confirm that `sifr` is on your PATH and reports a version:

    ```bash theme={null}
    sifr --version
    ```

    The current stable release reports `sifr 0.1.0`. If the command is not
    found, check that `~/.sifr/bin` is in your `PATH`.
  </Step>
</Steps>

## Install options

### Pin an exact version

If you need a reproducible stable setup, pass `--version` to the installer:

```bash theme={null}
curl -fsSL https://sifr.sh/install | sh -s -- --version 0.1.0
```

Only active versions present in the governed release index can be pinned.
Withdrawn or unknown versions fail before installer execution.

### Install to a custom directory

Set `SIFR_INSTALL_DIR` to place the managed binary directory somewhere other
than `~/.sifr/bin`. The installer writes the binary to
`SIFR_INSTALL_DIR/sifr` and, when the directory ends in `/bin`, installs the
sysroot next to that `bin` directory. For legacy flat custom directories that
do not end in `/bin`, the same directory is used as the sysroot root.

```bash theme={null}
curl -fsSL https://sifr.sh/install | SIFR_INSTALL_DIR="$HOME/.local/sifr/bin" sh
```

### Disable PATH modification

If you manage your PATH manually or are scripting the install in a CI pipeline, prevent the installer from touching your shell profile:

<CodeGroup>
  ```bash Environment variable theme={null}
  curl -fsSL https://sifr.sh/install | SIFR_NO_MODIFY_PATH=1 sh
  ```

  ```bash Flag theme={null}
  curl -fsSL https://sifr.sh/install | sh -s -- --no-modify-path
  ```
</CodeGroup>

## Keeping Sifr up to date

Sifr includes a built-in self-update command for installs created by the official installer script. Self-update uses the same GitHub-hosted channel metadata as the public installer.

```bash theme={null}
sifr self update
```

Before applying an update, use `--dry-run` to preview what the command would do without downloading anything:

```bash theme={null}
sifr self update --dry-run
```

### Switching channels

By default, `sifr self update` stays on the channel recorded in your install
receipt. Pass `--channel` to select stable or an explicit preview channel:

```bash theme={null}
sifr self update --channel stable
sifr self update --channel alpha
sifr self update --channel beta
```

### Pinning a version on update

You can update to a specific active stable version:

```bash theme={null}
sifr self update --version 0.1.0
```

### Reinstalls, downgrades, and channel switches

Same-version reinstalls, downgrades, and channel switches all require `--force`:

```bash theme={null}
sifr self update --version 0.1.0 --force
sifr self update --channel alpha --force
```

Regular updates to a newer version within your current channel do not need `--force`.

### Check your install details

`sifr self version` reports the current executable path, install directory,
sysroot path, channel, and receipt status:

```bash theme={null}
sifr self version
sifr self version --short   # prints only the version string
```

<Warning>
  `sifr self update` works only for standalone installs created by the
  official `https://sifr.sh/install` script. Source and package-manager
  installs are not managed by this command.
</Warning>

## Uninstall Sifr

Sifr does not currently include a `sifr self uninstall` command. To remove a standalone install created by the official installer, delete the installed toolchain root:

```bash theme={null}
rm -rf "$HOME/.sifr"
```

Then remove the installer-managed PATH source line from any shell profiles it updated. Look for this line:

```bash theme={null}
. "${HOME}/.sifr/env"
```

Depending on your shell, it may appear in one or more of these files:

* `~/.profile`
* `~/.bashrc`
* `~/.bash_profile`
* `~/.zshrc`

If you use fish, also remove the fish PATH helper:

```bash theme={null}
rm -f "$HOME/.config/fish/conf.d/sifr.env.fish"
```

Restart your shell, then confirm that `sifr` is no longer on your PATH:

```bash theme={null}
command -v sifr
```

If you installed Sifr to a custom directory with `SIFR_INSTALL_DIR`, remove
that toolchain root. If you installed Sifr from source or through another
distribution system, remove it through that same system.

## Troubleshooting

**Receipt missing or malformed.** If `sifr self update` reports that the install receipt is missing, predates the self-update rules, or is malformed, rerun the standalone installer to create a fresh receipt:

```bash theme={null}
curl -fsSL https://sifr.sh/install | sh
```

For a custom install directory, rerun the installer with the same environment variable:

```bash theme={null}
curl -fsSL https://sifr.sh/install | SIFR_INSTALL_DIR="$HOME/.local/sifr/bin" sh
```

**Wrong binary found on PATH.** If the diagnostic says the receipt belongs to a different executable, your `PATH` is resolving a different `sifr` binary. Run `command -v sifr` to see which one your shell finds, then either fix your PATH or reinstall the standalone binary so the receipt and executable match.

**Network failure mid-update.** If a metadata or installer download fails, retry after your network recovers. The existing binary and sysroot are not replaced until the delegated installer validates and stages the target artifact, so a failed update leaves your working toolchain intact.

See [stable releases](/releases/stable) for withdrawal and rollback behavior,
or [stable troubleshooting](/troubleshooting) for recovery steps.