Starship Prompt Complete Guide 2026: Cross-Shell Customization, Modules & Presets

Your terminal prompt is the most-viewed piece of text in your development workflow. It greets you thousands of times a day, yet most developers use a default prompt that shows nothing more than a dollar sign and a path. A great prompt tells you what branch you are on, whether you have uncommitted changes, what language runtime is active, and which cloud context you are targeting — all without running a single command.

Starship is the answer to every prompt frustration. Written in Rust for speed, designed for cross-shell compatibility, and configured through a single TOML file, Starship has become the de facto standard prompt for modern developers. This guide covers everything from installation to advanced customization, with real configuration examples you can copy directly into your starship.toml.

What Is Starship and Why It Matters

Starship is an open-source, cross-shell prompt written in Rust. It replaces your default shell prompt with a context-aware, information-rich line that automatically adapts to your current project. Walk into a Node.js project and Starship shows the Node version. Switch to a Python virtualenv and it displays the environment name. Check out a Git branch and it reveals the branch name with ahead/behind counts, staged changes, and untracked files.

Why does a cross-shell prompt matter? Developers frequently switch between shells — Bash on remote servers, Zsh on macOS, Fish on personal machines, PowerShell on Windows workstations. Shell-specific prompt frameworks like Oh My Zsh only work in one shell. Starship works everywhere with identical configuration, identical appearance, and identical behavior.

• Cross-shell: one config file for Bash, Zsh, Fish, PowerShell, Nushell, Cmd, Elvish, Tcsh, Xonsh
• Blazing fast: written in Rust, renders in under 10ms even with many modules enabled
• Context-aware: auto-detects Git, Node, Python, Rust, Go, Java, Docker, Kubernetes, AWS, GCP, Azure
• Single-file config: everything lives in ~/.config/starship.toml
• Over 50 built-in modules with sensible defaults — works great out of the box
• Active community with 45,000+ GitHub stars and frequent releases

Starship vs Oh My Zsh vs Powerlevel10k vs Pure

Each prompt tool serves different needs. This comparison helps you understand where Starship excels and where alternatives might be a better fit.

Installation

Starship distributes as a single binary. Install it with your preferred method, then add the init script to your shell configuration.

Install Script (Linux / macOS)

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

Homebrew (macOS / Linux)

brew install starship

Scoop (Windows)

scoop install starship

Cargo (Rust)

cargo install starship --locked

Package Managers

# Arch Linux
pacman -S starship

# Nix
nix-env -iA nixpkgs.starship

# Conda
conda install -c conda-forge starship

# Termux (Android)
pkg install starship

# Chocolatey (Windows)
choco install starship

# WinGet (Windows)
winget install --id Starship.Starship

Shell Setup (Bash, Zsh, Fish, PowerShell, Nushell, Cmd, Elvish, Tcsh, Xonsh)

After installing the Starship binary, you need to add a single line to your shell configuration file to activate it. Here is the init command for each supported shell.

Bash (~/.bashrc)

eval "$(starship init bash)"

Zsh (~/.zshrc)

eval "$(starship init zsh)"

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

starship init fish | source

PowerShell ($PROFILE)

Invoke-Expression (&starship init powershell)

Nushell

# In env.nu
mkdir ~/.cache/starship
starship init nu | save -f ~/.cache/starship/init.nu

# In config.nu
use ~/.cache/starship/init.nu

Other Shells

# Cmd (via Clink) — starship.lua in Clink scripts directory
load(io.popen('starship init cmd'):read("*a"))()

# Elvish (~/.elvish/rc.elv)
eval (starship init elvish)

# Tcsh (~/.tcshrc)
eval `starship init tcsh`

# Xonsh (~/.xonshrc)
execx($(starship init xonsh))

starship.toml Configuration Basics

All Starship configuration lives in ~/.config/starship.toml (or the path set by the STARSHIP_CONFIG environment variable). The file uses TOML format with sections for the overall prompt format and individual modules.

The top-level format key defines the prompt layout. Each module has its own section with options like format, style, symbol, and disabled. You can also set scan_timeout and command_timeout at the top level to control performance.

# ~/.config/starship.toml

# Top-level prompt format
format = """
\$directory\
\$git_branch\
\$git_status\
\$nodejs\
\$python\
\$rust\
\$docker_context\
\$cmd_duration\
\$line_break\
\$character"""

# Timeout for scanning directories (milliseconds)
scan_timeout = 30

# Timeout for commands run by modules
command_timeout = 500

# Blank line between prompts
add_newline = true

# Prompt character
[character]
success_symbol = "[>](bold green)"
error_symbol = "[>](bold red)"

Module System Overview

Starship uses a modular architecture. Each piece of information in your prompt is a module — git_branch, nodejs, python, directory, and so on. Modules are only shown when relevant: the nodejs module appears only when a package.json or .node-version file is detected in the current directory tree.

The default format string includes all built-in modules in a sensible order. You can override this to reorder modules, remove ones you do not need, or add custom modules. Each module supports a format string that controls exactly what text and symbols are displayed.

# Disable a module entirely
[package]
disabled = true

# Customize module format
[nodejs]
format = "via [Node \$version](bold green) "

# Change module symbol
[python]
symbol = "py "
format = 'via [\${symbol}\${pyenv_prefix}(\${version})(\(\$virtualenv\))](bold yellow) '

Git Status Module

The Git modules are the most popular Starship features. The git_branch module shows the current branch name with a customizable symbol. The git_status module displays a compact summary of your working tree state: staged, modified, untracked, deleted, renamed, and stashed counts, plus ahead/behind information relative to the upstream branch.

You can customize every symbol in git_status. The default symbols are concise but you can replace them with Nerd Font icons or emoji for a more visual experience. The git_commit module shows the current commit hash when in detached HEAD state, and git_state shows when you are in the middle of a rebase, merge, cherry-pick, or bisect.

[git_branch]
symbol = " "        # Nerd Font branch icon
style = "bold purple"
format = "on [\$symbol\$branch(:$remote_branch)](\$style) "

[git_status]
ahead = "A\${count} "
behind = "B\${count} "
diverged = "D\${ahead_count}/\${behind_count} "
staged = "+\${count} "
modified = "!\${count} "
untracked = "?\${count} "
deleted = "x\${count} "
stashed = "*\${count} "
style = "bold red"

[git_commit]
commit_hash_length = 7
tag_symbol = " "

[git_state]
rebase = "REBASING"
merge = "MERGING"
cherry_pick = "CHERRY-PICKING"

Visual prompt example showing Git status in action:

# Clean branch, ahead of remote by 2 commits
~/projects/myapp on  main A2 
> 

# Branch with staged and modified files
~/projects/myapp on  feature/auth +3 !2 ?1 
> 

# Detached HEAD during interactive rebase
~/projects/myapp on  a3f7c21 REBASING 3/5
> 

Language Detection Modules

Starship includes modules for virtually every programming language and runtime. Each language module detects specific files (like package.json for Node.js, Cargo.toml for Rust, or pyproject.toml for Python) and displays the active version. This is incredibly useful when switching between projects that require different runtime versions.

You can customize the symbol, style, and version format for each language module. The detect_files, detect_folders, and detect_extensions options let you fine-tune when each module activates.

# Node.js — detects package.json, .node-version, .nvmrc
[nodejs]
format = "via [ \$version](bold green) "
detect_files = ["package.json", ".node-version"]
detect_extensions = ["js", "mjs", "cjs", "ts", "mts"]

# Python — detects pyproject.toml, requirements.txt, .python-version
[python]
format = 'via [\${symbol}\${pyenv_prefix}(\${version})(\(\$virtualenv\))](bold yellow) '
symbol = " "

# Rust — detects Cargo.toml
[rust]
format = "via [ \$version](bold red) "

# Go — detects go.mod, go.sum, .go files
[golang]
format = "via [ \$version](bold cyan) "

# Java — detects pom.xml, build.gradle, .java files
[java]
format = "via [ \$version](bold red) "

# Ruby — detects Gemfile, .ruby-version
[ruby]
format = "via [ \$version](bold red) "

# PHP — detects composer.json, .php files
[php]
format = "via [ \$version](bold purple) "

Cloud and Kubernetes Modules

For DevOps and cloud engineers, Starship provides modules for AWS, Google Cloud, Azure, and Kubernetes. The aws module reads your AWS_PROFILE and region, the gcloud module shows the active GCP project and region, and the kubernetes module displays the current cluster and namespace from your kubeconfig.

These modules are disabled by default to avoid performance overhead for developers who do not use cloud CLIs. Enable them in your starship.toml when needed.

# AWS — reads AWS_PROFILE and region
[aws]
disabled = false
format = 'on [\$symbol(\$profile)(\(\$region\))](bold yellow) '
symbol = " "

[aws.region_aliases]
us-east-1 = "use1"
eu-west-1 = "euw1"

# Google Cloud
[gcloud]
disabled = false
format = 'on [\$symbol\$account(@\$domain)(\(\$region\))](bold blue) '
symbol = " "

# Azure
[azure]
disabled = false
format = "on [ \$subscription](bold blue) "

# Kubernetes — shows cluster and namespace
[kubernetes]
disabled = false
format = 'on [ \$context(\(\$namespace\))](bold purple) '

[kubernetes.context_aliases]
"arn:aws:eks:us-east-1:123456789:cluster/prod" = "prod"
"gke_myproject_us-central1_staging" = "staging"

Docker Context Module

The docker_context module displays the current Docker context, which is critical when switching between local development, remote Docker hosts, and container orchestration platforms. It only appears when the context is not set to the default, reducing prompt noise.

[docker_context]
format = "via [ \$context](bold blue) "
only_with_files = true
detect_files = ["docker-compose.yml", "docker-compose.yaml", "Dockerfile"]
detect_extensions = ["dockerfile"]

Directory Module Customization

The directory module controls how the current path is displayed. By default, Starship truncates long paths to three parent directories. You can customize the truncation length, truncation symbol, substitutions (replace long paths like ~/Developer/projects with short aliases), and whether to show the read-only symbol for directories where you lack write permission.

[directory]
truncation_length = 4
truncation_symbol = ".../""
truncate_to_repo = true
read_only = " "
style = "bold cyan"

# Path substitutions for shorter display
[directory.substitutions]
"~/Developer/projects" = "DEV"
"~/Documents/work" = "WORK"
"~/.config" = "CFG"

Custom Modules

Custom modules let you display any shell command output in your prompt. This is Starship's escape hatch for information that no built-in module covers. Define a custom module with a command, a when condition, and a format string. Starship caches the output based on the command_timeout setting.

Common custom module use cases include showing the current Terraform workspace, displaying the active tmux session, showing the number of background jobs, or indicating VPN connection status.

# Show current Terraform workspace
[custom.terraform]
command = "terraform workspace show"
when = "test -f main.tf"
format = "via [TF \$output](bold purple) "
shell = ["bash", "--noprofile", "--norc"]

# Show active tmux session
[custom.tmux]
command = "tmux display-message -p '#S' 2>/dev/null"
when = "test -n \"\$TMUX\""
format = "[ \$output](bold yellow) "

# VPN status indicator
[custom.vpn]
command = "echo connected"
when = "pgrep -x openvpn"
format = "[ VPN](bold green) "

Command Duration and Execution Time

The cmd_duration module shows how long the last command took to execute. By default it only appears when the command took longer than 2 seconds, keeping the prompt clean for quick commands. You can customize the threshold, format, and whether to show millisecond precision.

[cmd_duration]
min_time = 2_000          # Show only for commands > 2s
format = "took [\$duration](bold yellow) "
show_milliseconds = false
show_notifications = true  # Desktop notification for long commands
min_time_to_notify = 30_000  # Notify if > 30s

Battery Module

The battery module displays the current battery level and charging status. It is useful for laptop users who want a quick indicator without looking at the system tray. You can define custom thresholds with different symbols and styles for each battery level range.

[battery]
full_symbol = " "
charging_symbol = " "
discharging_symbol = " "

[[battery.display]]
threshold = 15
style = "bold red"

[[battery.display]]
threshold = 50
style = "bold yellow"

[[battery.display]]
threshold = 100
style = "bold green"

Time and Username Modules

The time module shows the current time in a configurable format. It is disabled by default but useful for developers who want timestamps in their terminal history. The username module displays the current user, which is especially helpful when SSHing into remote servers to confirm which user you are logged in as.

[time]
disabled = false
format = "at [ \$time](bold dimmed white) "
time_format = "%H:%M"
utc_time_offset = "local"

[username]
show_always = false    # Only show on SSH or root
style_root = "bold red"
style_user = "bold yellow"
format = "[\$user]($style) "

[hostname]
ssh_only = true
format = "on [\$hostname](bold dimmed green) "
trim_at = "."

Nerd Font Icons and Symbols

Nerd Fonts are patched fonts that include thousands of icons from Font Awesome, Devicons, Octicons, and other icon sets. Starship uses Nerd Font symbols by default for language icons, Git symbols, and other glyphs. To see these icons correctly, install a Nerd Font and set it as your terminal font.

Popular Nerd Font choices include FiraCode Nerd Font, JetBrainsMono Nerd Font, and Hack Nerd Font. If you prefer not to use Nerd Fonts, Starship provides a text-only preset that replaces all icons with plain ASCII characters.

# Install Nerd Font on macOS
brew install --cask font-fira-code-nerd-font
brew install --cask font-jetbrains-mono-nerd-font

# Switch to text-only symbols (no Nerd Font needed)
starship preset plain-text-symbols -o ~/.config/starship.toml

Color and Style Customization

Starship styles use a string format that combines foreground color, background color, and text attributes. The format is "fg:color bg:color attributes" where attributes include bold, italic, underline, dimmed, inverted, and strikethrough. Colors can be standard terminal color names, hex codes, or ANSI 256 color numbers.

# Style syntax examples
[directory]
style = "bold cyan"                    # Bold cyan foreground

[git_branch]
style = "fg:#a6e3a1 bold"              # Hex color, bold

[nodejs]
style = "fg:green bg:#1e1e2e bold"     # Green on dark background

[cmd_duration]
style = "fg:220 italic"                # ANSI 256 color, italic

# Define reusable color palettes (Starship 1.17+)
palette = "catppuccin_mocha"

[palettes.catppuccin_mocha]
rosewater = "#f5e0dc"
mauve = "#cba6f7"
red = "#f38ba8"
peach = "#fab387"
green = "#a6e3a1"
blue = "#89b4fa"
text = "#cdd6f4"

Preset Themes

Starship ships with several built-in presets that completely change the look and feel of your prompt. Apply a preset with the starship preset command, which overwrites your starship.toml with the preset configuration.

You can use a preset as a starting point and then customize individual modules. The preset command also supports outputting to stdout so you can review the configuration before applying it.

# List all available presets
starship preset --list

# Apply Tokyo Night preset
starship preset tokyo-night -o ~/.config/starship.toml

# Apply Gruvbox Rainbow preset
starship preset gruvbox-rainbow -o ~/.config/starship.toml

# Apply Pastel Powerline preset
starship preset pastel-powerline -o ~/.config/starship.toml

# Apply Nerd Font Symbols preset
starship preset nerd-font-symbols -o ~/.config/starship.toml

# Apply Bracketed Segments preset
starship preset bracketed-segments -o ~/.config/starship.toml

# Apply Plain Text preset (no special fonts needed)
starship preset plain-text-symbols -o ~/.config/starship.toml

# Preview a preset before applying
starship preset tokyo-night

Performance Comparison

Prompt performance matters because a slow prompt makes every command feel sluggish. Starship is written in Rust and optimized for speed. It runs each module in parallel and caches results aggressively. The typical render time is 5-15ms, compared to 50-200ms for Oh My Zsh themes and 20-50ms for Powerlevel10k with instant prompt disabled.

You can benchmark your Starship configuration with the built-in timings command, which breaks down render time by module so you can identify and disable slow modules.

# Benchmark your current Starship config
starship timings

# Example output:
# directory 0.8ms | git_branch 1.2ms | git_status 3.1ms
# nodejs 1.5ms | character 0.1ms | Total 6.7ms

# Optimize: reduce command timeout for slow modules
command_timeout = 200

# Disable modules you do not use
[php]
disabled = true

Right Prompt Configuration

Starship supports right-side prompts in shells that support them (Zsh, Fish, PowerShell, Elvish, Nushell). The right_format key in starship.toml defines what appears on the right side. Common choices include the time module, command duration, and status code.

# Right-side prompt configuration
right_format = """
\$cmd_duration\
\$time"""

[cmd_duration]
format = "[\$duration](dimmed yellow)"

[time]
disabled = false
format = "[\$time](dimmed white)"
time_format = "%H:%M:%S"

Conditional Modules

You can make modules appear only in certain directories by combining the detect_files, detect_folders, and detect_extensions options. Custom modules support a when condition that runs a shell command and shows the module only when the command succeeds (exit code 0).

This is useful for showing project-specific information: display the Terraform workspace only in directories containing .tf files, or show a custom deployment target only when a deploy.yaml is present.

# Show Terraform module only in directories with .tf files
[terraform]
format = "via [TF \$version \$workspace](bold purple) "
detect_files = [".terraform", "main.tf"]

# Custom module with when condition
[custom.deploy_target]
command = "cat deploy.yaml | grep target | cut -d: -f2"
when = "test -f deploy.yaml"
format = "deploy:[\$output](bold red) "

# Show Python only for Python projects
[python]
detect_files = ["pyproject.toml", "requirements.txt", "setup.py", "Pipfile"]
detect_extensions = []  # Do not trigger on .py files in non-Python projects

Integration with tmux and screen

Starship works seamlessly inside tmux and GNU screen sessions. Since Starship modifies the shell prompt (not the terminal emulator), it renders correctly regardless of the terminal multiplexer. For tmux users, you can show the active tmux session name in your prompt using a custom module.

# Custom module to show tmux session in prompt
[custom.tmux_session]
command = "tmux display-message -p '#S' 2>/dev/null"
when = "test -n \"\$TMUX\""
format = "[ \$output](bold yellow) "
shell = ["bash", "--noprofile", "--norc"]

# Tip: Add to your format string
# format = "\${custom.tmux_session}\$directory\$git_branch..."

Creating and Sharing Presets

To create a shareable preset, craft your starship.toml with all desired module configurations, then share the file directly or host it as a URL. Others can apply it with starship preset or by copying the file to their config directory. The Starship community maintains a repository of user-contributed presets.

# Share your config directly
cp ~/.config/starship.toml ~/my-starship-preset.toml

# Apply a preset from a URL
curl -sS https://example.com/my-preset.toml \
  -o ~/.config/starship.toml

# Apply a preset from a local file
cp ~/shared-configs/team-preset.toml ~/.config/starship.toml

# Use STARSHIP_CONFIG env var for per-project presets
export STARSHIP_CONFIG=~/projects/myapp/.starship.toml

Common Configurations by Use Case

Different workflows benefit from different prompt configurations. Here are optimized setups for three common developer profiles.

Web Development

# Optimized for web development
format = """
\$directory\
\$git_branch\$git_status\
\$nodejs\
\$bun\
\$deno\
\$docker_context\
\$cmd_duration\
\$line_break\
\$character"""

[nodejs]
format = "via [ \$version](bold green) "

[bun]
format = "via [ \$version](bold white) "

[deno]
format = "via [ \$version](bold green) "

# Disable irrelevant modules
[aws]
disabled = true
[gcloud]
disabled = true
[java]
disabled = true

DevOps / Cloud Engineering

# Optimized for DevOps / Cloud Engineering
format = """
\$username\$hostname\$directory\
\$git_branch\$git_status\
\$kubernetes\$aws\$gcloud\$terraform\
\$docker_context\$cmd_duration\
\$line_break\$character"""

[kubernetes]
disabled = false
format = '[ \$context(\(\$namespace\))](bold purple) '

[aws]
disabled = false
format = '[ \$profile(\(\$region\))](bold yellow) '

[terraform]
format = "via [TF \$version \$workspace](bold purple) "

Data Science / ML

# Optimized for Data Science / ML
format = """
\$directory\$git_branch\$git_status\
\$python\$conda\$julia\$rlang\
\$docker_context\$cmd_duration\
\$line_break\$character"""

[python]
format = 'via [\${symbol}(\${version})(\(\$virtualenv\))](bold yellow) '
symbol = " "

[conda]
format = "via [ \$environment](bold green) "

# Show long-running training times
[cmd_duration]
min_time = 5_000
show_notifications = true

Tips and Tricks for Power Users

• Tip 1: Use starship timings to identify slow modules and optimize your prompt render time
• Tip 2: Set STARSHIP_CACHE to a ramdisk path for even faster module caching on Linux
• Tip 3: Use env_var module to display custom environment variables like API endpoints or deployment targets
• Tip 4: Combine directory substitutions to create short aliases for deep project paths
• Tip 5: Use the status module to show exit codes and signal names for failed commands
• Tip 6: Set scan_timeout to a lower value (like 20ms) on slow filesystems such as NFS or SSHFS
• Tip 7: Add a line_break module between the info line and the input line for a two-line prompt layout
• Tip 8: Use palettes in starship.toml to define reusable color names for consistent theming

Frequently Asked Questions