Starship Terminal Prompt: Install and Usage Guide

Introduction

Starship is a cross-platform terminal prompt written in Rust — fast (< 10ms startup), out of the box, and supports Bash, Zsh, Fish, PowerShell, and more.

Key features:

Fast: < 10ms startup, almost imperceptible
Cross-platform: Same experience on macOS, Linux, and Windows
Config-as-code: A single starship.toml manages everything
Smart detection: Auto-displays Git, Node.js, Python, Docker, and more

macOS Installation

1. Install Starship

brew install starship

2. Initialize in Shell Config

Zsh (~/.zshrc):

eval "$(starship init zsh)"

Bash (~/.bashrc):

eval "$(starship init bash)"

Fish (~/.config/fish/config.fish):

starship init fish | source

3. Verify

Restart the terminal and run:

starship --version

Expected output: starship 1.x.x

4. Uninstall

brew uninstall starship

Then remove the eval "$(starship init ...)" line from your shell config.

Windows Installation

Method 1: Scoop (Recommended)

scoop install starship

Method 2: winget

winget install --id Starship.Starship

Method 3: Manual

Download starship-x86_64-pc-windows-msvc.zip from GitHub Releases, extract to C:\Program Files\starship\, and add it to your PATH.

Initialize in PowerShell

Edit $PROFILE:

Invoke-Expression (&starship init powershell)

Verify

starship --version

Linux Installation

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

The script detects your architecture and installs to ~/.local/bin/. Make sure that directory is in your PATH, then add eval "$(starship init zsh)" to ~/.zshrc or ~/.bashrc.

Font Configuration (Nerd Font)

Starship uses Nerd Font icons, so you need one installed.

macOS

brew install --cask font-fira-code-nerd-font
brew install --cask font-jetbrains-mono-nerd-font

Windows

Download and install JetBrains Mono Nerd Font or Fira Code Nerd Font from Nerd Fonts Releases.

Configure Your Terminal

Set the font in your terminal settings to the Nerd Font you just installed.

Basic Configuration

Config file location:

macOS / Linux: ~/.config/starship.toml
Windows: %USERPROFILE%\.config\starship.toml

Minimal Config

mkdir -p ~/.config && touch ~/.config/starship.toml

# starship.toml
add_newline = false

[character]
success_symbol = "[➜](bold green)"
error_symbol = "[➜](bold red)"

Common Modules

[directory]
style = "bold cyan"
truncation_length = 3
truncation_symbol = "…/"

[git_branch]
symbol = "🌱 "

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

[nodejs]
symbol = "⬢ "
style = "bold green"

[python]
symbol = "🐍 "
style = "bold yellow"

Using Presets

Starship offers several official presets:

# List available presets
starship preset --list

# Apply a preset
starship preset tokyo-night > ~/.config/starship.toml

Popular presets: tokyo-night, gruvbox-rainbow, pastel-powerline, pure-preset.

Troubleshooting

Garbled characters

Cause: Nerd Font not installed. See the font configuration section above.

Module not showing

starship explain   # Check current config
starship print     # Print the current prompt

Slow startup

starship timings   # Check module timing

Disable unused modules to optimize:

[package]
disabled = true

[python]
disabled = true

Wrong colors

Ensure your terminal supports true color:

echo $COLORTERM
# Expected: truecolor or 256color