Starship Prompt — Build a Custom Shell Prompt for Productivity

In this tutorial, you'll learn about Starship Prompt. We cover key concepts, practical examples, and best practices to help you understand and apply this topic effectively.

Starship is a cross-shell prompt that displays contextual information — Git branch, language version, command duration, directory path, and exit codes — in a fast, customizable, and minimal prompt.

What You'll Learn

How to install and configure Starship for any shell, customize modules for Git, Node.js, Python, Rust, and Docker, theme the prompt with custom colors and formatting, optimize performance, and create a prompt that shows exactly what you need without clutter.

Why Starship Matters

A good shell prompt saves seconds many times per day — showing the Git branch, whether files are modified, the current Node.js or Python version, and whether the last command failed. The default shell prompt shows only the username and hostname. Starship shows everything relevant about your current context in one line, with modules that activate only when needed. Doda Browser's engineering team standardized on Starship across macOS, Linux, and CI environments for consistent prompt behavior.

Learning Path

flowchart LR
  A[fzf & zoxide] --> B[Starship Prompt
You are here]
  B --> C[mise/asdf]
  B --> D[Zsh & Oh My Zsh]
  style B fill:#f90,color:#fff

Installation

# macOS
brew install starship

# Ubuntu/Debian
sudo snap install starship
# Or:
curl -sS https://starship.rs/install.sh | sh

# Fedora
sudo dnf install starship

# Arch
sudo pacman -S starship

# Verify installation
starship --version

Shell Configuration

Add one line to your shell config:

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

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

# ~/.config/fish/config.fish (fish)
starship init fish | source

# ~/.config/powershell/Microsoft.PowerShell_profile.ps1
Invoke-Expression (&starship init powershell)

Default Prompt

With no custom configuration, Starship shows:

~/projects/website on main [!] via v23.5.0
❯

This shows: current directory, Git branch, unstaged changes indicator, active Node.js version, and a clean prompt character.

Configuration

Starship configuration lives in ~/.config/starship.toml:

# Don't show until a command takes longer than this
command_timeout = 500

# Disable the default newline
add_newline = true

# Format string — order of modules
format = """
[](#9A348E)\
$os\
$shell\
$username\
[](bg:#DA627D fg:#9A348E)\
$directory\
[](fg:#DA627D bg:#B12F53)\
$git_branch\
$git_status\
[](fg:#B12F53 bg:#D5A021)\
$nodejs\
[](fg:#D5A021 bg:#61C0BF)\
$python\
[](fg:#61C0BF bg:#34558B)\
$rust\
[](fg:#34558B bg:#4B3B60)\
$docker_context\
$fill\
$cmd_duration\
$line_break\
$character\
"""

Git Module

[git_branch]
format = "[\\($branch\\)]($style)"
style = "bold purple"
symbol = " "

[git_status]
conflicted = " equals"
ahead = "⇡${count}"
behind = "⇣${count}"
diverged = "⇕${ahead_count}${behind_count}"
staged = "{\"+\"$count}"
modified = "!$count"
stashed = "\\$$count"
deleted = "✗$count"
renamed = "»$count"
untracked = "?$count"

Language Modules

[nodejs]
format = "via [⬢ $version](bold green) "
detect_files = ["package.json", ".node-version"]
detect_folders = ["node_modules"]

[python]
format = "via [🐍 $version]($style) "
style = "bold yellow"
python_binary = "python3"

[rust]
format = "via [🦀 $version]($style) "
style = "bold red"
detect_files = ["Cargo.toml"]

[golang]
format = "via [🐹 $version]($style) "
style = "bold cyan"

[docker_context]
format = "via [🐳 $context]($style) "
style = "blue bold"
only_with_files = true

Directory Module

[directory]
truncation_length = 3
truncate_to_repo = true
style = "bold blue"
format = "[$path]($style)[$read_only]($read_only_style) "

Custom Modules

[custom.terraform]
command = "terraform version"
when = "test -d .terraform"
format = "via [🟪 $version]($style) "

[custom.kubectl]
command = "kubectl config current-context 2>/dev/null"
when = "test -f kubeconfig || test -f ~/.kube/config"
format = "via [☸️ $output]($style) "
style = "bold red"

Performance and Visual Settings

# Right-align a module
# In the format string, include $fill before right-aligned modules

[fill]
symbol = " "

# Command duration
[cmd_duration]
min_time = 2000  # Show only for commands taking >2s
format = "took [$duration]($style) "
style = "yellow italic"

# Character
[character]
success_symbol = "[❯](bold green)"
error_symbol = "[❯](bold red)"
vimcmd_symbol = "[❮](bold green)"

Nerd Font Icons

Starship uses Nerd Font icons for maximum visual density:

# Ensure your terminal uses a Nerd Font (e.g., FiraCode Nerd Font, JetBrainsMono Nerd Font)
[aws]
symbol = "☁️"

[git_branch]
symbol = " "

[package]
symbol = "📦"

Minimal Prompt for Performance

format = "$directory$git_branch$fill$cmd_duration$character"

[directory]
truncation_length = 2

[git_branch]
format = "[\\($branch\\)]($style)"

[cmd_duration]
min_time = 5000
format = "⏱ $duration"

[character]
success_symbol = "[❯]"

Multiple-Line Prompt

format = """
[](#9A348E)\
$username\
[](bg:#DA627D fg:#9A348E)\
$directory\
[](fg:#DA627D bg:#B12F53)\
$git_branch\
$git_status\
[](fg:#B12F53 bg:#D5A021)\
$nodejs\
$fill\
$cmd_duration\
$line_break\
$character\
"""

Testing Your Prompt

# Show current Starship configuration
starship config --list

# Print prompt as plain text (for debugging)
starship prompt

# Preview different presets
starship preset nerd-font-symbols -o ~/.config/starship.toml
starship preset pastel-powerline -o ~/.config/starship.toml
starship preset bracketed-segments -o ~/.config/starship.toml

# Toggle a module on/off
starship toggle nodejs

Real-World Configuration

# ~/.config/starship.toml
add_newline = true
command_timeout = 1000

format = """
[](#1a1b26)\
$os\
[](#1a1b26 fg:#7dcfff)\
$directory\
$git_branch\
$git_status\
$fill\
$cmd_duration\
$line_break\
[](fg:#7dcfff)\
$character\
"""

[os]
disabled = false
style = "bg:#1a1b26 fg:#7dcfff"
format = "[ $symbol]($style)"

[directory]
style = "fg:#7dcfff"
truncation_length = 3
truncate_to_repo = true

[git_branch]
format = "[$symbol$branch]($style)"
style = "fg:#bb9af7"
symbol = " "

[git_status]
style = "fg:#bb9af7"
conflicted = " equals"
ahead = "⇡${count}"
behind = "⇣${count}"
diverged = "⇕${ahead_count}${behind_count}"
staged = "+\${count}"
modified = "!\${count}"
stashed = "\\$$count"
deleted = "✗\${count}"
renamed = "»\${count}"
untracked = "?\${count}"

[nodejs]
format = "via [⬢ $version]($style) "
style = "fg:#7dcfff"
detect_files = ["package.json", ".node-version"]

[cmd_duration]
min_time = 3000
format = "[⏱ $duration]($style)"
style = "fg:#565f89"

[character]
success_symbol = "[❯](fg:#7dcfff)"
error_symbol = "[❯](fg:#f7768e)"

Common Errors

1. Starship Prompt Very Slow

Check for slow commands in custom modules. Each custom module runs its command on every prompt. Cache results or use when conditions to limit execution. Also verify command_timeout is set.

2. Icons and Symbols Show as Boxes

Your terminal font does not support Nerd Font symbols. Install a Nerd Font (FiraCode, JetBrainsMono, Hack Nerd Font) and set it in your terminal emulator.

3. Git Module Not Showing

You are not in a Git Repository, or the Git Repository is in a parent directory. Starship detects Git repos by searching upward. Run git status to verify the repo is initialized.

4. Prompt Shows Different Format in Different Terminals

Each terminal may have different Starship configuration paths. Ensure $XDG_CONFIG_HOME is consistent, or use --config flag: eval "$(starship init zsh --config ~/.config/starship/mylaptop.toml)".

5. Custom Module Runs Every Prompt

Without a when condition, the custom module command runs on every prompt. Add when = true or a file check: when = "test -f Makefile".

6. Python Version Shows Wrong Interpreter

Starship uses python --version by default. On systems where python points to Python 2, set python_binary = "python3".

7. Duplicate Module Entries

Multiple presets or config files are being loaded. Check $STARSHIP_CONFIG and merge all config into one file.

Practice Questions

1. How do you change the truncation length of the directory module? Set truncation_length = 3 in the [directory] section. The default is 3 directory components.

2. What module shows the Git branch and status? [git_branch] shows the branch name. [git_status] shows staged, modified, deleted, and untracked file indicators.

3. How do you show command duration only for commands that took longer than 2 seconds? Set [cmd_duration] min_time = 2000. Commands faster than 2 seconds do not show the duration.

4. What causes Starship to show version information for a language? Starship detects language-specific files (e.g., package.json for Node.js, Cargo.toml for Rust, requirements.txt for Python) and shows the version only in directories containing those files.

5. How do you create a custom module that shows a Terraform version? Define [custom.<a href="/devops/terraform/">Terraform</a>] with command = "<a href="/devops/terraform/">Terraform</a> version" and when = "test -d .<a href="/devops/terraform/">Terraform</a>".

Challenge: Create a Starship configuration that: (1) shows Git branch, status, and ahead/behind counts, (2) displays Node.js and Python versions when relevant files are present, (3) shows Docker context when in a project with a Dockerfile, (4) displays command duration for commands over 1 second, (5) uses a two-line prompt with right-aligned time, (6) applies a Tokyo Night color scheme. Test it in a real project with all these context elements.

What's Next

Built by the developers of Doda Browser, DodaZIP, and Durga Antivirus Pro. Updated 2026-06-24.