Starship Shell Prompt

Starship cheatsheet — blazing-fast shell prompt for bash, zsh, fish. Install via curl, customize starship.toml, enable modules for git, node, python, docker, and more.

6 min read

What it is

Starship is a minimal, blazing-fast, and infinitely customizable prompt for any shell, showing you essential information about the context you’re in.

Installation

Linux/macOS (using package managers):

  • Homebrew:
    brew install starship
  • Cargo (Rust’s package manager):
    cargo install starship
  • Nix:
    nix-env -iA nixpkgs.starship
  • Arch Linux:
    sudo pacman -S starship
  • Debian/Ubuntu (via apt, if available):
    # Check for availability or add a PPA if one exists.
# Example (may vary):
# curl -s https://starship.rs/gpg.key | sudo gpg --dearmor -o /usr/share/keyrings/starship.gpg
# echo "deb [signed-by=/usr/share/keyrings/starship.gpg] https://starship.rs/deb/ any main" | sudo tee /etc/apt/sources.list.d/starship.list
# sudo apt update
# sudo apt install starship

Windows:

  • Scoop:
    scoop install starship
  • Chocolatey:
    choco install starship
  • Winget:
    winget install starship
  • Cargo:
    cargo install starship

Add to your shell configuration:

After installation, add the following line to your shell’s configuration file:

  • Bash: ~/.bashrc or ~/.bash_profile
    eval "$(starship init bash)"
  • Zsh: ~/.zshrc
    eval "$(starship init zsh)"
  • Fish: ~/.config/fish/config.fish
    starship init fish | source
  • PowerShell: Microsoft.PowerShell_profile.ps1 (find its location with $PROFILE)
    Invoke-Expression (&starship init powershell)
  • Nushell: env.nu
    starship init nu | source

Then, restart your shell or run source ~/.bashrc (or your respective config file).

Core Concepts

Starship is built around modules. Each module displays specific information (e.g., Git status, Node.js version, current directory). These modules are enabled or disabled and configured via a JSON configuration file. Starship automatically detects the context for many modules (like Git in a Git repository, or Python version in a Python project). The prompt is constructed by composing these modules in a specific order.

Commands / Usage

Starship itself is primarily a prompt, so its "commands" are mostly related to configuration and status.

Configuration:

  • Display default config:

    starship --config-version

    (This command actually shows the config version, not the config itself. To view the default config, refer to the Starship documentation or create your own.)

  • Get current config file path:

    starship --config-file

    This will output the path to your Starship configuration file (usually ~/.config/starship.toml).

  • Open config file in default editor:

    starship --edit-config

    This command opens your starship.toml file in your default text editor.

  • Show configuration documentation:

    starship --help

    Displays general help and lists available modules and their configuration options.

Status:

  • Show Starship version:

    starship --version

    Displays the installed version of Starship.

  • Show configuration version:

    starship --config-version

    Displays the version of the configuration format that Starship is using.

Common Patterns

Starship’s power lies in its configuration (~/.config/starship.toml). Here are common configuration patterns and examples:

1. Basic Git Integration:

By default, Starship shows Git information. You can customize its appearance:

# ~/.config/starship.toml

[git_branch]
symbol = "🌱 "
format = '[$symbol$branch]($style)'

[git_status]
style = "bold red"
format = ' ([$all_status$ahead_in_commit_count](bold red) [$staged](green) [$untracked](yellow) [$ignored](grey))'
staged = "[+]"
untracked = "[?]"
ahead = "⇡"
diverged = "⇕"
behind = "⇣"

Explanation:

  • git_branch: Configures the display of the current Git branch. symbol adds an emoji, format defines how it looks.
  • git_status: Configures the display of Git status indicators. style sets the color, format defines the appearance of different statuses (staged, untracked, etc.).

2. Node.js Version:

Display the current Node.js version in your project.

# ~/.config/starship.toml

[nodejs]
symbol = "λον " # Example: Using a Nerd Font glyph
format = '[$symbol($version)]($style)'

Explanation:

  • nodejs: Enables the Node.js module. symbol adds an icon, format controls the output string.

3. Python Version:

Show the active Python environment and version.

# ~/.config/starship.toml

[python]
symbol = "🐍 "
format = '[$symbol($version)]($style)'
disabled = false # Explicitly enable if needed

Explanation:

  • python: Enables the Python module.

4. Docker/Kubernetes Context:

Show the current Docker or Kubernetes context.

# ~/.config/starship.toml

[docker_context]
symbol = "🐳 "
format = '[$symbol$context]($style)'

[kubernetes]
symbol = "☸ "
format = '[$symbol$context]($style)'

Explanation:

  • docker_context: Displays the current Docker context.
  • kubernetes: Displays the current Kubernetes context.

5. Current Directory:

Customize how the current directory is displayed, including truncation.

# ~/.config/starship.toml

[directory]
truncation_length = 4
fish_style_pwd_dir = 'blue bold'
style = "bold blue"
format = '[$style](#ff0066)[❯]($style)[ ](default)[$path]($style)'

Explanation:

  • directory: Controls the current directory display.
  • truncation_length: Shortens the path to the specified number of characters from the end.
  • fish_style_pwd_dir: Applies specific styling for directories in Fish shell.
  • format: Allows complex string formatting.

6. Time Module:

Display the current time.

# ~/.config/starship.toml

[time]
format = '[$symbol]($style) [$time]($style)'
time_format = "%T" # HH:MM:SS
use_12_hour_format = true
disabled = false

Explanation:

  • time: Enables the time module.
  • time_format: Uses strftime format codes for time display.

7. Customizing the Prompt Structure:

The format string in the [starship] section controls the overall layout.

# ~/.config/starship.toml

[starship]
format = """
$username\
$hostname\
$directory\
$git_branch\
$git_status\
$nodejs\
$python\
$time\
$character\
"""

Explanation:

  • format: This is the main template for the entire prompt. Modules are placed here using $module_name. Newlines (\) can be used for multi-line prompts. $character is usually the final prompt symbol (like ❯ or #).

8. Conditional Disabling:

Disable a module under certain conditions.

# ~/.config/starship.toml

[git_commit]
disabled = true # Hide commit hash by default

Explanation:

  • disabled = true: Prevents the git_commit module from showing unless explicitly enabled or configured otherwise.

9. Customizing the Prompt Character:

The character at the very end of the prompt.

# ~/.config/starship.toml

[character]
success_symbol = "[❯](green)"
error_symbol = "[✖](red)"
vim_insert_symbol = "[INSERT](yellow)"
vim_normal_symbol = "[NORMAL](blue)"
vim_visual_symbol = "[VISUAL](cyan)"

Explanation:

  • success_symbol: Symbol shown when the previous command succeeded.
  • error_symbol: Symbol shown when the previous command failed.
  • Vim symbols (if vim_mode module is enabled): Change symbols based on Vim’s mode.

Gotchas

  • Configuration File Location: Starship looks for starship.toml in ~/.config/starship.toml. If it’s not found, it uses a default configuration. Make sure your file is in the correct location.
  • Shell Integration: Ensure eval "$(starship init <shell>)" (or equivalent) is correctly added to your shell’s startup file (.bashrc, .zshrc, etc.) and that you’ve restarted your shell or sourced the file.
  • Nerd Fonts: Many custom symbols (like those used in [nodejs], [docker_context], etc.) require a Nerd Font to be installed and configured as your terminal’s font. If symbols appear as boxes or question marks, this is likely the cause.
  • Performance: While Starship is very fast, complex configurations or modules that run slow external commands can impact prompt rendering time. Test your configuration if you notice slow prompts.
  • Module Order: The order in which modules are listed in the [starship] section’s format directly affects the order they appear in the prompt.
  • Overriding Defaults: If a module doesn’t appear as expected, check if it’s explicitly disabled (disabled = true) in your configuration or if its format is empty.
  • starship.toml vs starship.json: Starship primarily uses TOML for configuration (starship.toml). While JSON is supported, TOML is the recommended and more common format.