How to Configure a Custom Prompt With Starship

Starship is a prompt tool that works identically across Bash, Zsh, and fish, handling the genuinely fiddly work of fast, correct prompt rendering — git status, language version detection, command timing — so you don’t have to hand-write it yourself.

Step 1: install Starship

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

Package manager installs are also available (brew install starship on macOS, for instance) if you’d prefer not to run the install script directly.

Step 2: add Starship’s initialization to your shell’s config

# Bash: in ~/.bashrc
eval "$(starship init bash)"

# Zsh: in ~/.zshrc
eval "$(starship init zsh)"

This single line is what actually activates Starship as your prompt — without it, Starship is installed but not yet in use.

Step 3: reload your shell to see the default prompt

exec $SHELL

Starship’s default configuration already shows useful context — current directory, git branch and status, and language-specific version indicators when relevant (a Python virtual environment, a Node.js project) — with zero further configuration required.

Step 4: generate a starting configuration file

mkdir -p ~/.config
starship preset nerd-font-symbols -o ~/.config/starship.toml

Starship ships several built-in presets — this example uses one assuming a Nerd Font is installed for icon glyphs; check starship preset --list for alternatives if you’re not using a patched font.

Step 5: customize which modules appear

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

[package]
disabled = true

Starship’s configuration is organized into modules — one per piece of information it can show — each independently enableable, disableable, and stylable.

Step 6: customize the format and ordering of prompt segments

format = """
$directory\
$git_branch\
$git_status\
$character"""

The format string controls exactly which modules appear and in what order — a genuinely direct way to build precisely the prompt layout you want, rather than working around a theme’s fixed layout.

Step 7: adjust performance-sensitive modules if startup feels slow

[git_status]
disabled = false

[cmd_duration]
min_time = 500

If prompt display feels slow in specific large repositories, checking module-specific settings like git_status’s scan behavior (or disabling it project-by-project via .starship_disabled files, per Starship’s own documentation) addresses the specific cause rather than disabling Starship’s git integration entirely.

Step 8: verify the configuration file is valid

starship config

This opens the configuration file in your default editor and validates it, useful for catching a TOML syntax error before it causes confusing prompt behavior.

Why a shell-agnostic prompt tool is genuinely useful, not just convenient

Since Starship works identically regardless of which shell you’re actually running, switching between Bash, Zsh, or fish across different machines or contexts doesn’t mean maintaining separate prompt configurations for each — one starship.toml file produces the same prompt everywhere Starship is initialized, which is a meaningfully different guarantee than shell-specific PS1 string configuration provides.