Starship

What is Starship?

Starship is a minimal, fast, and customizable prompt for any shell. It is written in Rust and works across Bash, Zsh, Fish, and more. It replaces theme-based prompt systems (like Oh My Zsh themes or Powerlevel10k) with a single, cross-shell configuration.

Prerequisites

A terminal emulator with Nerd Font support (such as Ghostty) is recommended but not required.

Installation

brew install starship

curl -sS https://starship.rs/install.sh | sh

Initialize Starship

Add to your ~/.zshrc:

command -v starship &>/dev/null && eval "$(starship init zsh)"

Using a command -v guard ensures the shell does not error if Starship is not installed on a particular machine. This is important for shared dotfiles.

Lazy-Loading Shell Integrations

The command -v + eval pattern used above is fast for tools like Starship and zoxide. But heavier tools — language version managers like nvm, pyenv, or rbenv — can add 200–500ms each to shell startup. For those, defer initialization until first use:

# Lazy-load nvm — only runs init when you first call nvm (Zsh-only)
nvm() {
  unfunction nvm  # Zsh builtin; use "unset -f nvm" in Bash
  source "$NVM_DIR/nvm.sh"
  nvm "$@"
}

Use lazy-loading for tools you do not invoke in every shell session. Keep tools you use constantly (like Starship and zoxide) eager. See the Dotfiles guide for more on cross-platform shell optimization.

Choose a Preset

Starship includes several presets to get started quickly:

# List available presets
starship preset --list

# Apply a preset (e.g., Tokyo Night)
mkdir -p ~/.config
starship preset tokyo-night -o ~/.config/starship.toml

Customize Starship

Edit ~/.config/starship.toml to tailor the prompt:

[directory]
truncation_length = 3
truncation_symbol = "…/"

[git_branch]
symbol = " "

[git_status]
conflicted = "⚡"
ahead = "⇡${count}"
behind = "⇣${count}"

[cmd_duration]
min_time = 500
format = "took [$duration](bold yellow) "

[time]
disabled = false
format = "[$time]($style) "
time_format = "%H:%M"

Manage with Dotfiles

To manage Starship config with GNU Stow:

mkdir -p ~/my-dotfiles/shared/starship/.config
mv ~/.config/starship.toml ~/my-dotfiles/shared/starship/.config/starship.toml
cd ~/my-dotfiles
stow -d shared -t ~ starship

Companion CLI Tools

These modern CLI tools complement Starship and integrate well with a shared dotfiles setup.

zoxide — Smarter cd

zoxide learns your most-used directories and lets you jump to them with partial names.

brew install zoxide

curl -fsSL https://raw.githubusercontent.com/ajeetdsouza/zoxide/main/install.sh | sh

Add to your ~/.zshrc:

command -v zoxide &>/dev/null && eval "$(zoxide init zsh)"

Usage:

# Jump to a frequently-used directory
z projects

# Interactive selection
zi

eza — Modern ls

eza is a modern replacement for ls with colors, icons, and Git integration.

brew install eza

sudo apt install eza

Add an alias to your ~/.zshrc:

command -v eza &>/dev/null && alias ls='eza -la --icons'

Troubleshooting

command not found: starship after install

On Linux, the installer places Starship in /usr/local/bin. Ensure this is on your PATH:

export PATH="/usr/local/bin:$PATH"

Starship prompt is slow

Starship scans the current directory for language files, Git status, etc. In large repos, this can be slow. Disable expensive modules:

# ~/.config/starship.toml
[git_status]
disabled = true

Resources

🔗

Starship Configuration starship.rs

Complete reference for all Starship prompt modules and options

🔗

Mac Terminal Setup with Ghostty and Starship bitdoze.com

Step-by-step guide for configuring a modern terminal environment