Starship is a minimal, blazing-fast, and infinitely customizable prompt for any shell! Written in Rust, it provides a beautiful and feature-rich terminal prompt that works across different shells and operating systems.
Table of contents
Open Table of contents
Why Starship?
If you’ve been using the default terminal prompt or even oh-my-zsh themes, you might wonder why you should switch to Starship. Here are the compelling reasons:
Performance
- Lightning fast: Written in Rust, Starship is significantly faster than traditional shell themes
- Minimal startup time: No noticeable delay when opening new terminal sessions
- Efficient: Only shows relevant information when needed
Cross-Shell Compatibility
- Works with Bash, Zsh, Fish, PowerShell, and more
- Consistent experience across different shells and operating systems
- Easy migration between different terminal environments
Rich Features Out of the Box
- Git integration: Shows branch, status, and repository information
- Language detection: Automatically detects and displays versions for 30+ programming languages
- Cloud provider info: AWS, GCP, Azure context display
- Kubernetes context: Shows current cluster and namespace
- Custom modules: Create your own information modules
Installation
Prerequisites
Before installing Starship, ensure you have a Nerd Font installed and enabled in your terminal. Nerd Fonts provide the special symbols and icons that make Starship look beautiful.
Popular Nerd Fonts:
- Fira Code Nerd Font
- JetBrains Mono Nerd Font
- Source Code Pro Nerd Font
- Hack Nerd Font
Download from: https://www.nerdfonts.com/
Install Starship
Choose your preferred installation method:
Option 1: Install Script (Recommended)
# Cross-platform install script
curl -sS https://starship.rs/install.sh | sh
Option 2: Package Managers
# macOS (Homebrew)
brew install starship
# Ubuntu/Debian
curl -sS https://starship.rs/install.sh | sh
# Arch Linux
pacman -S starship
# Windows (Chocolatey)
choco install starship
# Windows (Scoop)
scoop install starship
Shell Configuration
Add the initialization script to your shell’s configuration file:
For Zsh (.zshrc)
# Disable oh-my-zsh theme if using it
ZSH_THEME=""
# Add Starship initialization to the end of ~/.zshrc
eval "$(starship init zsh)"
For Bash (.bashrc)
# Add to ~/.bashrc
eval "$(starship init bash)"
For Fish (config.fish)
# Add to ~/.config/fish/config.fish
starship init fish | source
Configuration
Starship uses a TOML configuration file located at ~/.config/starship.toml
. Create this file to customize your prompt.
Basic Configuration
Create the config directory and file:
mkdir -p ~/.config
touch ~/.config/starship.toml
Essential Configuration
Here’s a well-balanced configuration that provides useful information without clutter:
# ~/.config/starship.toml
# Global settings
add_newline = true
command_timeout = 1000
# Custom format - define what appears in your prompt
format = """
$username\
$hostname\
$directory\
$git_branch\
$git_status\
$git_state\
$python\
$nodejs\
$rust\
$golang\
$java\
$docker_context\
$kubernetes\
$aws\
$cmd_duration\
$line_break\
$character"""
# Disable cloud info to reduce clutter
[gcloud]
disabled = true
[azure]
disabled = true
# Disable package version info for cleaner look
[package]
disabled = true
# Keep only essential language info
[nodejs]
format = "via [⬢ $version](bold green) "
detect_files = ["package.json", ".nvmrc"]
[python]
format = "via [🐍 $version]($style) "
detect_extensions = ["py"]
[rust]
format = "via [⚙️ $version](red bold) "
# Git configuration
[git_branch]
format = "on [$symbol$branch]($style) "
symbol = "🌱 "
style = "bold purple"
[git_status]
format = '([\[$all_status$ahead_behind\]]($style))'
style = "bold red"
[directory]
format = "in [$path]($style)[$read_only]($read_only_style) "
style = "bold cyan"
truncation_length = 3
truncate_to_repo = true
# Command duration - show if over 2 seconds
[cmd_duration]
min_time = 2_000
format = "took [$duration]($style) "
style = "bold yellow"
# Character prompt
[character]
success_symbol = "[❯](bold green)"
error_symbol = "[❯](bold red)"
My config
# Disable cloud info (Google Cloud, AWS, etc.)
[gcloud]
disabled = true
[aws]
disabled = true
[azure]
disabled = true
# Disable package version info
[package]
disabled = true
# Disable Node.js version
[nodejs]
disabled = true
# Disable Python version
[python]
disabled = true
# Keep only essential info
[git_branch]
format = "[$symbol$branch]($style) "
[directory]
format = "[$path]($style) "
truncation_length = 3
Advanced Configuration Examples
For DevOps Engineers
# Show Kubernetes context
[kubernetes]
format = 'on [⛵ $context \($namespace\)](dimmed green) '
disabled = false
# Show AWS profile
[aws]
format = 'on [$symbol($profile )(\($region\) )]($style)'
symbol = "☁️ "
style = "bold blue"
# Show Docker context
[docker_context]
format = "via [🐋 $context](blue bold) "
For Web Developers
# Show Node.js version always
[nodejs]
format = "via [⬢ $version](bold green) "
disabled = false
# Show package version
[package]
format = "is [📦 $version](208 bold) "
disabled = false
Useful Features
Git Integration
Starship automatically detects Git repositories and shows:
- Current branch name
- Repository status (staged, modified, untracked files)
- Ahead/behind commit count
- Repository state (merging, rebasing, etc.)
Language Detection
Automatically detects and shows versions for:
- JavaScript/Node.js (package.json)
- Python (.py files, virtual environments)
- Rust (Cargo.toml)
- Go (go.mod)
- Java (.java files)
- And 25+ more languages
Cloud Provider Context
- AWS: Shows current profile and region
- Google Cloud: Shows active project
- Azure: Shows active subscription
- Kubernetes: Shows current context and namespace
Performance Tips
- Selective Module Loading: Only enable modules you actually use
- Timeout Settings: Adjust
command_timeout
for slow networks - Disable Unused Features: Turn off package detection for faster prompts
# Disable slow modules
[gcloud]
disabled = true
[package]
disabled = true
# Reduce timeout for faster response
command_timeout = 500
Troubleshooting
Common Issues
Symbols not displaying correctly
- Ensure you have a Nerd Font installed and enabled
- Check your terminal’s font settings
Prompt is slow
- Reduce
command_timeout
value - Disable unused modules
- Check network connectivity for cloud modules
Git status not showing
- Ensure you’re in a Git repository
- Check Git configuration and permissions
Testing Configuration
Test your configuration without restarting your shell:
# Reload configuration
exec $SHELL
# Or source your shell config
source ~/.zshrc # for zsh
source ~/.bashrc # for bash
Comparison with Oh-My-Zsh
Feature | Oh-My-Zsh | Starship |
---|---|---|
Performance | Slower startup | Lightning fast |
Cross-shell | Zsh only | All major shells |
Customization | Theme-based | Module-based |
Maintenance | Active but complex | Simple and modern |
Dependencies | Heavy | Minimal |
Presets and Themes
Starship comes with several built-in presets you can use as starting points:
# Apply a preset
starship preset nerd-font-symbols -o ~/.config/starship.toml
starship preset bracketed-segments -o ~/.config/starship.toml
starship preset plain-text-symbols -o ~/.config/starship.toml
Integration with Development Tools
Cursor IDE
If you’re using Cursor IDE (mentioned in your tags), Starship works seamlessly with its integrated terminal, providing the same beautiful prompt experience.
Docker Development
[docker_context]
format = "via [🐋 $context](blue bold) "
only_with_files = false
Virtual Environments
[python]
format = 'via [${symbol}${pyenv_prefix}(${version} )(\($virtualenv\) )]($style)'
Conclusion
Starship transforms your terminal experience with:
- Beautiful aesthetics that don’t compromise performance
- Intelligent context that adapts to your development environment
- Cross-platform consistency across shells and operating systems
- Minimal configuration with maximum functionality
Whether you’re a beginner looking for a better terminal experience or a power user wanting fine-grained control, Starship provides the perfect balance of beauty, performance, and functionality.