Set up a fast cross-shell prompt with starship

Install starship, load it in bash, zsh or fish, edit starship.toml, apply a preset, and fix slow prompts or missing Nerd Font glyphs.

how-to6 steps

Updated

in short

Install the starship binary, add one starship init line to the end of your shell's rc file, then change the prompt in ~/.config/starship.toml. The same config file works in every shell you use.

starship is a single binary that prints your prompt. Each shell calls it before drawing the prompt, so bash, zsh and fish share one config file instead of three separate prompt scripts.

This guide installs it, loads it in your shell, walks through the config file and presets, and covers the two problems people hit most: a slow prompt and boxes or question marks where icons should be.

Tools used

Before you start

  • bash, zsh or fish (starship also supports nushell, PowerShell, elvish, tcsh, xonsh and others)
  • A Nerd Font installed and selected in your terminal, or use the no-nerd-font preset in step 5
  • A package manager such as Homebrew, pacman, dnf, winget or Scoop, or curl for the install script

Steps

  1. Step 1: Install starship

    Use your package manager if it has the package. On Linux and macOS the project's install script downloads the latest release; it only uses sudo when the target directory is not writable. Pass -b ~/.local/bin to install without root.

    sh
    # macOS or Linux with Homebrew
brew install starship

# Arch Linux
sudo pacman -S starship

# Any Linux or macOS, official install script
curl -sS https://starship.rs/install.sh | sh
    sh
    starship --version

  2. Step 2: Load starship in your shell

    Add the line for your shell to the end of its rc file. It has to come after anything else that sets the prompt, such as a framework theme, or that code will overwrite it.

    bash
    # ~/.bashrc
eval "$(starship init bash)"
    zsh
    # ~/.zshrc
eval "$(starship init zsh)"
    fish
    # ~/.config/fish/config.fish
starship init fish | source

  3. Step 3: Open a new shell

    Start a new terminal tab, or run exec $SHELL to replace the current shell. You should see the default prompt: the current directory, git branch and status when inside a repository, language versions when the directory contains matching project files, and a ❯ character that turns red after a failed command.

  4. Step 4: Create starship.toml

    starship works without a config file. To change anything, create ~/.config/starship.toml. Top-level keys apply to the whole prompt; each [section] configures one module. The $schema line gives editors completion and validation for the file.

    This example removes the blank line between prompts, changes the prompt character, shows more of the path and hides the package version module.

    sh
    mkdir -p ~/.config && touch ~/.config/starship.toml
    toml
    "$schema" = 'https://starship.rs/config-schema.json'

# No blank line between prompts
add_newline = false

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

[directory]
# Default is 3 parent folders
truncation_length = 5

[package]
disabled = true

  5. Step 5: Start from a preset

    Presets are complete config files that ship inside the binary. starship preset --list prints their names, and -o writes one to a file. Writing a preset replaces your config, so move an existing starship.toml aside first.

    nerd-font-symbols uses Nerd Font icons for every module. no-nerd-font only uses emoji and powerline symbols, so it renders without a Nerd Font. plain-text-symbols uses no icons at all.

    sh
    starship preset --list
    sh
    mv ~/.config/starship.toml ~/.config/starship.toml.bak
starship preset nerd-font-symbols -o ~/.config/starship.toml

  6. Step 6: Use a different config path (optional)

    To keep the file somewhere else, for example in a dotfiles repository, set STARSHIP_CONFIG before the starship init line.

    sh
    export STARSHIP_CONFIG=~/dotfiles/starship.toml

Troubleshooting

  • Prompt is slow to appear: run env STARSHIP_LOG=trace starship timings in that directory. It lists every module that took over 1ms or printed output, so you can see which one to disable.
  • Executing command "..." timed out warnings: a module's command took longer than command_timeout (500 ms by default). Raise it at the top of starship.toml, or set STARSHIP_LOG=error to hide the warnings.
  • Slow git_status in WSL under /mnt/c/: the module is slow on Windows drives. Set disabled = true under [git_status], or point its windows_starship option at a Windows starship binary.
  • Large repositories or slow disks: lower scan_timeout (default 30 ms), the time starship spends scanning the current directory for project files.
  • Boxes or question marks instead of icons: your terminal is not using a Nerd Font. Install one and select it in the terminal's font settings, or switch to the no-nerd-font preset.
  • Glyphs still missing with a Nerd Font set: check that your locale is UTF-8 and an emoji font is installed. echo -e "\xee\x82\xa0" should print a branch symbol.
  • Prompt did not change: another line later in the rc file resets the prompt. Move the starship init line to the very end.

Tips

  • starship explain describes each module currently shown in your prompt, useful when you see a symbol you do not recognise.
  • env STARSHIP_LOG=trace starship module git_status runs one module on its own with debug logs.
  • Every module has a disabled option, so you can turn off anything you do not need.

Also worth a look

  • fishHas a configurable prompt built in if you only use one shell.
  • NushellA structured-data shell; starship supports Nushell 0.96 and newer.

FAQ

Do I need a Nerd Font to use starship?
No, but the default config uses some Nerd Font symbols. Without one, apply the no-nerd-font or plain-text-symbols preset so every symbol renders.
Can I use the same config on several machines and shells?
Yes. The prompt is defined only in starship.toml, so copying that file, or pointing STARSHIP_CONFIG at a synced copy, gives the same prompt in every supported shell.
How do I remove starship?
Delete the starship init line from your rc file, then uninstall it with your package manager. If you used the install script, remove the binary with rm "$(command -v starship)".

related

starship detailsfish detailsnushell details