Skip to content

INSTALLATION.md

Latest commit

 

History

History
372 lines (268 loc) · 11.8 KB

INSTALLATION.md

File metadata and controls

372 lines (268 loc) · 11.8 KB
Raw

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"

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