hereink

How to install Starship on macOS/Linux: configure starship.toml for zsh and fish

Install Starship, tune starship.toml, and enable a cross-shell prompt in zsh or fish.

When you need Git branch, path depth, and command duration in one glance, the default PS1 is often too sparse or messy. Starship is a Rust cross-shell prompt: one init line hooks into zsh or fish, with settings in ~/.config/starship.toml. This guide covers official installs on macOS and Linux plus first-time tuning for hereink readers who live in the terminal.

The query is how to install Starship on macOS/Linux and configure zsh or fish. You should finish with the binary installed, init lines in place, a working starship.toml, and a prompt that shows Git and slow-command timing.

Installbrew · install.sh · cargo
Config~/.config/starship.toml
Shellzsh · fish · bash

What Starship fixes

Easier than hand-rolled PS1

Raw PS1 escape sequences are hard to read and share. Starship modules (directory, git_branch, cmd_duration) live in TOML—you change themes without shell scripts.

Same look across shells

zsh on macOS, bash on a remote box, fish locally: one starship.toml keeps the prompt consistent and cuts context switching.

Official docs: starship.rs. After install run starship --version; the Configuration page documents every module.

Install on macOS and Linux

  1. 1
    macOS (Homebrew, recommended)

    Run brew install starship. Verify with which starship and starship --version. Same formula on Apple Silicon and Intel.

  2. 2
    Linux distro packages

    Debian/Ubuntu: add the official repo then apt install starship (see the install page on starship.rs). Fedora: dnf install starship. Arch: pacman -S starship or AUR.

  3. 3
    Universal install script

    No package manager: curl -sS https://starship.rs/install.sh | sh. The script prints the bin path; you usually need ~/.local/bin on PATH.

  4. 4
    Optional: cargo

    With Rust installed: cargo install starship --locked. Slower compile, useful when prebuilt binaries are unavailable.

Hook into zsh or fish

# zsh — append to ~/.zshrc
eval "$(starship init zsh)"

# fish — append to ~/.config/fish/config.fish
starship init fish | source

# bash — append to ~/.bashrc if you use bash
eval "$(starship init bash)"

Save, then open a new terminal or source the file. If nothing changes, confirm starship is on PATH (echo $PATH).

Edit ~/.config/starship.toml

ModuleRoleExample
[directory]Current path, can truncatetruncation_length = 3
[git_branch]Git branch and statesymbol = " "
[cmd_duration]Slow command timingmin_time = 500 (ms)
formatGlobal module orderformat = "$directory$git_branch$character"
Fits
Daily coding in zsh/fish, hopping Git repos, wanting a lightweight prompt you can version-control.
Does not fit
Jump hosts that mandate legacy PS1; terminals that cannot use Nerd Fonts and reject plain-text symbols.
command not found: starship after install?

The binary is not on PATH. Homebrew users: eval "$(/opt/homebrew/bin/brew shellenv)" on Apple Silicon or check /usr/local/bin. install.sh users: export ~/.local/bin in .zshrc.

Does it clash with Oh My Zsh themes?

Disable or comment ZSH_THEME when Starship is active—keep only the starship init line or prompts may stack.

Config changes do nothing?

Edit ~/.config/starship.toml, not a copy in a project folder. TOML errors fall back to defaults; run starship config or see Troubleshooting in the docs.

Then align on one diagram

Once the shell feels right, service boundaries still belong on one shared board. See how to create a space.

Start a room