Customizing your command-line interface doesn't mean wrestling with cryptic escape sequences or slow plugin managers. Starship TOML configuration lets you build a blazing-fast, cross-shell prompt that displays Git status, language versions, and system metrics only when you actually need them. Written in Rust, Starship renders in milliseconds and works identically whether you use Bash, Zsh, Fish, or PowerShell.
If you're tired of a sluggish terminal or a bland default prompt, setting up a dedicated configuration file transforms your daily workflow. This guide walks through installing Starship, structuring your starship.toml file, organizing module layouts, and troubleshooting common performance bottlenecks.
Getting Started with Starship
Before tweaking configuration files, you need to install the binary and hook it into your shell. Starship relies on a single initialization line in your shell profile and reads its primary settings from a central file located at ~/.config/starship.toml.
Installation and Shell Hook
You can install Starship using a shell script, Homebrew, or your package manager. For most Unix-like systems, the official install script is the fastest route:
curl -sS https://starship.rs/install.sh | sh
Once installed, you must tell your shell to load Starship upon startup. Add the appropriate init line to your configuration file:
- For Bash (
~/.bashrc):eval "$(starship init bash)" - For Zsh (
~/.zshrc):eval "$(starship init zsh)" - For Fish (
~/.config/fish/config.fish):starship init fish | source
After saving your shell configuration file, restart your terminal or run source ~/.bashrc (or your respective shell config). You'll immediately see the default Starship prompt.
Creating Your Configuration File
Starship works out of the box with sensible defaults, but true customization requires creating a configuration file. Create the configuration directory and empty TOML file with:
mkdir -p ~/.config && touch ~/.config/starship.toml
Open this file in your preferred text editor. You can point Starship to an entirely different path if you manage your dotfiles elsewhere by exporting the STARSHIP_CONFIG environment variable in your shell profile:
export STARSHIP_CONFIG="$HOME/.dotfiles/starship/starship.toml"
Structuring the starship.toml File
The starship.toml file controls global behavior, module layouts, and visual styling. Starship uses the TOML format, which relies on key-value pairs and tables (brackets) to organize settings.
Global Settings
At the very top of your starship.toml, you can set global preferences that affect how the entire prompt behaves:
# Adds a blank line between shell prompts for readability
add_newline = true
# Timeout in milliseconds for git operations before canceling
command_timeout = 500
# Limit directory path depth to keep the prompt short
[directory]
truncation_length = 3
truncation_symbol = "…/"
By default, Starship enables the $all variable, which injects every available module that detects an active context. However, defining a explicit format string gives you total control over module order:
format = """
$directory\
$git_branch\
$git_status\
$nodejs\
$python\
$character"""
Configuring Individual Modules
Every chunk of information—such as your Git branch, Node.js version, or command execution duration—is an independent module. You can customize their appearance, symbols, and conditions.
For example, you can customize the character module to change your prompt symbol based on whether your previous command succeeded or failed:
[character]
success_symbol = "[➜](bold green)"
error_symbol = "[✗](bold red)"
vicmd_symbol = "[V](bold yellow)"
To enable language-specific modules like Python or Node.js, you simply declare their tables:
[python]
symbol = "🐍 "
format = "via [$symbol($version )(\\($virtualenv\\))]($style)"
[nodejs]
symbol = "⬢ "
detect_files = ["package.json", ".node-version"]
If a module displays information you don't care about, disable it entirely within its block:
[package]
disabled = true
Advanced Customization Techniques
Once you have your basic modules aligned, you can introduce advanced styling features to make your terminal visually cohesive without sacrificing speed.
Defining Color Palettes
Instead of scattering hardcoded color strings across dozens of modules, you can define a centralized palette. This makes it easy to switch your terminal theme on the fly:
palette = "custom_dark"
[palettes.custom_dark]
accent = "#7aa2f7"
muted = "#565f89"
success = "#9ece6a"
danger = "#f7768e"
[character]
success_symbol = "[❯](bold accent)"
error_symbol = "[❯](bold danger)"
Managing Git Performance
One of the most common reasons a prompt feels sluggish is heavy Git repository scanning. If you work in massive repositories with thousands of untracked files, Starship's git_status module might slow down. You can optimize performance by ignoring submodules or setting scan timeouts:
[git_status]
disabled = false
ignore_submodules = true
map_style = "bold red"
Common Mistakes to Avoid
When building a custom starship.toml, users often run into a few recurring pitfalls:
- Syntax Errors in TOML: Missing a quotation mark or misplacing a bracket will cause Starship to fall back to default behavior or throw parsing warnings. Always validate your syntax after major edits.
- Forgetting to Handle Missing Fonts: Many Starship presets rely on Nerd Fonts for glyphs and icons. If your terminal renders boxes or question marks instead of icons, install a patched Nerd Font and select it in your terminal emulator preferences.
- Overloading the Prompt: Enabling all 50+ modules clutters your screen. Stick to context-aware modules that appear only when relevant, keeping your workspace clean.
Refer to the Starship Configuration Documentation for a comprehensive list of every available module and setting. You can also explore community setups via the Starship Presets Gallery to find layouts tailored to specific developer workflows.
Frequently Asked Questions
Why isn't my starship.toml file updating my prompt?
Starship reads the configuration file fresh on every single render. If your changes aren't showing up, verify that your file is located precisely at ~/.config/starship.toml (or that your STARSHIP_CONFIG environment variable points to the correct file). Check for syntax errors by running starship explain or inspecting terminal warning messages upon startup.
How do I find out why a specific module is showing up?
Run the starship explain command in your terminal. This utility inspects your current directory context and lists every active module alongside the exact reason it is currently being displayed.
Can I use Starship across multiple different shells?
Yes. Starship is shell-agnostic. Because your visual layout and module rules are entirely contained within the single starship.toml file, you can move between Bash, Zsh, Fish, and PowerShell on different machines while maintaining an identical prompt experience.
How can I debug slow prompt rendering?
If your terminal starts lagging when changing directories, run starship timings. This command breaks down the exact execution time of every active module, allowing you to identify and disable resource-heavy checks like deep Git status scans.
