Installation Guide

This guide covers the complete installation process for xfetch on Linux, macOS, and Windows.

Prerequisites

The installer follows a no-sudo-by-default design: everything is installed in your user space (~/.local/bin, ~/.config/xfetch), and sudo is only ever used to install missing system dependencies, always after asking for your confirmation first. Nothing else requires privileges.

• bash — present on virtually every Linux/macOS system (required to run the script itself)
• curl — used by the remote one-liner and by rustup
• git — for cloning the repository (not needed for the remote one-liner)
• Rust/Cargo — the build toolchain. If not installed, the installer can set it up via rustup, fully in user space (no sudo)
• C compiler — a C toolchain is required to link Rust binaries: build-essential (Debian/Ubuntu), base-devel (Arch), devel_basis pattern (openSUSE), Xcode Command Line Tools (macOS), etc.

If any of these are missing, the installer asks you in the terminal and installs them for you automatically (using your distro's package manager, with sudo only for that step). In non-interactive environments (CI, containers) it never uses sudo without authorization: either pass --install-deps or run the printed command yourself.

Quick Install (Recommended)

The fastest way to install xfetch. No sudo is required — if your system already has a C toolchain, this installs xfetch entirely in your user space. If something is missing (Rust, C compiler, git, curl), the installer asks and handles it automatically.

Linux / macOS

curl -fsSL https://raw.githubusercontent.com/xfetch-cli/xfetch/main/install.sh | bash

Prefer no toolchain? The prebuilt installer downloads the verified binary from the latest release (no Rust, no compilation):

curl -fsSL https://raw.githubusercontent.com/xfetch-cli/xfetch/main/install-prebuilt.sh | bash

If cargo is not installed, the script will offer to install Rust via rustup automatically.

If system dependencies are missing, it will ask for your confirmation and then prompt for your sudo password to install them (only that step uses sudo):

In non-interactive environments (CI, containers), pass --install-deps to pre-authorize the dependency installation:

curl -fsSL https://raw.githubusercontent.com/xfetch-cli/xfetch/main/install.sh | bash -s -- --install-deps

WSL

WSL is treated as a normal Linux system by the installer — no special steps are needed. If your WSL distribution runs as root by default, pass --yes to skip the root confirmation prompt.

curl -fsSL https://raw.githubusercontent.com/xfetch-cli/xfetch/main/install.sh | bash -s -- --yes

Windows (PowerShell)

Prebuilt (no Rust needed):

irm https://raw.githubusercontent.com/xfetch-cli/xfetch/main/install-prebuilt.ps1 | iex

From source (installs Rust via rustup when missing, then builds):

irm https://raw.githubusercontent.com/xfetch-cli/xfetch/main/install.ps1 | iex

What the Script Does

1. Preflight checks: writable home, disk space, network reachability
2. Checks for Rust (offers to install it if missing, via rustup, no sudo)
3. Clones the repository
4. Builds the binary with cargo build --release --locked
5. Installs it to ~/.local/bin/
6. Sets up default config files in ~/.config/xfetch/
7. Adds ~/.local/bin to your PATH (via ~/.bashrc, ~/.zshrc, ~/.zprofile, or config.fish)

Install Script Options

The install script supports several flags for customization:

# Install missing system dependencies automatically (prompts for sudo)
bash <(curl -fsSL https://raw.githubusercontent.com/xfetch-cli/xfetch/main/install.sh) --install-deps

# Install to a custom prefix
bash <(curl -fsSL https://raw.githubusercontent.com/xfetch-cli/xfetch/main/install.sh) --prefix /usr/local

# Skip PATH modification
bash <(curl -fsSL https://raw.githubusercontent.com/xfetch-cli/xfetch/main/install.sh) --no-modify-path

# Install from a local clone of the repository
git clone https://github.com/xfetch-cli/xfetch.git
cd xfetch
bash install.sh --local

# Non-interactive install (auto-yes to prompts)
bash install.sh --local --yes

For all available flags:

bash <(curl -fsSL https://raw.githubusercontent.com/xfetch-cli/xfetch/main/install.sh) --help

Local Install

If you have already cloned the repository, run the installer directly from the project root:

cd xfetch
bash install.sh --local

This skips the git clone step and builds from your local copy.

Build from Source (Manual)

For full control over the build:

# Clone
git clone https://github.com/xfetch-cli/xfetch.git
cd xfetch

# Build release binary
cargo build --release

# The binary is at: target/release/xfetch
# Install it manually:
cp target/release/xfetch ~/.local/bin/

# Generate a starter config (adds the distro ASCII logo when online)
xfetch --gen-config

Additional presets are available in xfetch-cli/configs.

Install via Cargo

Install the latest release straight from crates.io (the installed command is xfetch):

cargo install xfetch-cli

This installs to ~/.cargo/bin/ (ensure it is in your PATH).

Alternatively, install from a local clone of the repository:

cargo install --path .

macOS (Homebrew)

The easiest way to install xfetch on macOS is via Homebrew. No Rust toolchain or compilation is needed — a prebuilt binary is downloaded and verified against its SHA256 checksum. It works on both Apple Silicon (arm64) and Intel (x86_64) Macs.

brew tap xfetch-cli/tap
brew install xfetch

To update to a newer release:

brew upgrade xfetch

To uninstall:

brew uninstall xfetch

Note: because Homebrew installs the binary directly (without macOS quarantine), no code signing or Gatekeeper bypass is required.

Arch Linux (AUR)

xfetch is packaged in the Arch User Repository as xfetch-core-bin (precompiled binary) and xfetch-git (builds from source). With an AUR helper such as yay:

yay -S xfetch-core-bin   # precompiled binary
yay -S xfetch-git        # build from source

Without an AUR helper, clone the package repository and build it manually:

git clone https://aur.archlinux.org/xfetch-core-bin.git
cd xfetch-core-bin
makepkg -si

Installs system-wide to /usr/bin/xfetch.

To uninstall the package:

sudo pacman -R xfetch-core-bin

Packages are maintained in the AUR, not in the xfetch repository, so update them with pacman -Syu (or your AUR helper); xfetch update never replaces a package-manager install.

Verifying Installation

After installing, verify xfetch works:

xfetch --version

You should see version output. Then run it to test the display:

xfetch

Troubleshooting "command not found"

If you get a "command not found" error:

• Restart your terminal, or
• Run source ~/.bashrc (or source ~/.zshrc), or
• Manually add ~/.local/bin to your PATH:

export PATH="$HOME/.local/bin:$PATH"

Verifying Release Signatures

Every release publishes SHA256SUMS. From v1.0.1 onward each release also ships sigstore (cosign) signature material, SHA256SUMS.bundle, produced by the release workflow through GitHub Actions OIDC — there is no long-lived signing key to trust — plus a GitHub build provenance attestation per archive.

Download the checksums, the bundle and (optionally) the archive you want, then verify manually (requires cosign and gh):

VERSION=1.0.2
ASSET="xfetch-${VERSION}-x86_64-unknown-linux-gnu.tar.gz"
BASE="https://github.com/xfetch-cli/xfetch/releases/download/v${VERSION}"

curl -fsSLO "${BASE}/SHA256SUMS"
curl -fsSLO "${BASE}/SHA256SUMS.bundle"
curl -fsSLO "${BASE}/${ASSET}"

# 1. Verify the signature over SHA256SUMS
cosign verify-blob \
  --bundle SHA256SUMS.bundle \
  --certificate-identity "https://github.com/xfetch-cli/xfetch/.github/workflows/release.yml@refs/tags/v${VERSION}" \
  --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
  SHA256SUMS

# 2. Verify the archive against the signed checksums
sha256sum -c SHA256SUMS --ignore-missing
# macOS without coreutils:
#   shasum -a 256 -c SHA256SUMS --ignore-missing
# neither available:
#   openssl dgst -sha256 "${ASSET}"   (compare by hand)

# 3. Check the build provenance attestation
gh attestation verify "${ASSET}" --repo xfetch-cli/xfetch

The expected signing identity is https://github.com/xfetch-cli/xfetch/.github/workflows/release.yml@refs/tags/v* and the OIDC issuer is https://token.actions.githubusercontent.com.

What the prebuilt installer enforces

install-prebuilt.sh is fail-closed by default:

• The release tag is authoritative. The version comes from the release JSON tag_name (validated as a strict dotted numeric version), never from the asset filename. The asset must be named exactly xfetch-<tag-version>-<target>.tar.gz (or .zip), and --version must match the tag; otherwise the installer aborts.
• SHA256SUMS is mandatory. If it cannot be fetched, is empty, does not list the archive, or the digest does not match, the installer aborts.
• Signatures are mandatory from v1.0.1. If SHA256SUMS.bundle is missing for such a release, the installer aborts; a signature that fails to verify always aborts, even with --allow-unsigned.
• Older releases (before v1.0.1) were never signed: their missing bundle produces a warning and SHA-256-only install.
• No cosign installed produces a warning and continues after the SHA-256 check. Pass --require-signature to make a missing cosign (or missing bundle) fatal.
• Hashing tools: sha256sum, then shasum -a 256 (macOS), then openssl dgst -sha256. If none exists the installer aborts rather than skipping verification.

Escape hatches, both of which are explicit and noisy:

• --allow-unsigned accepts a v1.0.1+ release whose signature bundle is missing (SHA-256 only). It does not accept an invalid signature.
• --no-checksum disables both the SHA-256 and the signature checks. It is dangerous and only appropriate for an archive you obtained through an already-authenticated channel. It cannot be combined with --require-signature.

install.sh builds from source and never downloads release binaries, so the signature check does not apply to it; the same is true for cargo install, Homebrew and AUR installs, whose integrity is guaranteed by the registry or package manager you use. The Windows prebuilt installer (install-prebuilt.ps1) verifies SHA256SUMS but does not yet verify the cosign bundle.

Updating

xfetch can check for and install new releases itself:

xfetch update --check   # only report; exits 1 when a newer release exists
xfetch update           # install the newest release
xfetch update --yes     # skip the confirmation prompt

The command detects how the binary was installed before touching anything:

• Prebuilt installs (install-prebuilt.sh, typically ~/.local/bin): the matching release asset is downloaded, verified against the published SHA256SUMS, extracted and moved over the current executable with an atomic rename. A single xfetch.bak keeps the previous binary and is overwritten on the next update.
• cargo installs (~/.cargo/bin): updated with cargo install xfetch-cli --force --locked.
• Package-manager installs and local builds: never replaced; the command prints the right command instead.

xfetch update --prebuilt --bin-dir <dir> forces the in-place update of <dir>/xfetch (Unix only). On Windows the prebuilt path is not available yet; use cargo install xfetch-cli --force or your installer of choice.

GH_TOKEN or GITHUB_TOKEN raise the GitHub API rate limit, and XFETCH_UPDATE_API overrides the release endpoint (useful for mirrors and tests).

Uninstallation

See the Uninstallation Guide for detailed instructions.

Quick uninstall:

curl -fsSL https://raw.githubusercontent.com/xfetch-cli/xfetch/main/uninstall.sh | bash

Uninstall including config files and PATH entries:

curl -fsSL https://raw.githubusercontent.com/xfetch-cli/xfetch/main/uninstall.sh | bash -s -- --purge

Manual removal:

rm -f ~/.local/bin/xfetch
rm -rf ~/.config/xfetch

Next Steps

• Configuration Guide — customize modules, logos, colors, and layouts
• Config Generation Guide — generate a starter config with the distro logo and your layout
• Layouts Guide — explore built-in display layouts
• Plugins Guide — extend xfetch with external plugins