Starship Prompt Tutorial: Build a Blazing Fast, Custom Terminal Prompt

Let’s be honest: the default terminal prompt is boring. It tells you where you are and who you are, but it doesn’t tell you anything useful about your current project. After spending years tweaking Zsh themes and fighting with slow loading times, I finally switched to Starship. In this starship prompt tutorial, I’m going to show you how to transform your CLI from a plain text line into a powerful information dashboard.

What makes Starship different is that it’s written in Rust. If you’re interested in why that matters, check out my list of the best Rust-based CLI tools; the speed difference is night and day compared to traditional shell scripts. Starship provides a single configuration file that works across Bash, Zsh, Fish, and PowerShell.

Prerequisites

Before we dive into the installation, ensure you have the following ready:

A Unix-like environment (macOS, Linux) or Windows with WSL2.
A Nerd Font installed. This is non-negotiable. Starship uses glyphs for Git, Node.js, and Python icons. I recommend JetBrains Mono Nerd Font or FiraCode Nerd Font.
Basic familiarity with the terminal.

Step 1: Installing Starship

Installing Starship is straightforward. Depending on your OS, run the corresponding command:

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

If you are on Arch Linux, you can simply use pacman -S starship. Once the binary is installed, you need to tell your shell to actually use it. This is where most people get stuck.

Activating for Zsh

Add this line to the end of your ~/.zshrc file:

eval "$(starship init zsh)"

Activating for Bash

Add this to your ~/.bashrc:

eval "$(starship init bash)"

After saving the file, restart your terminal or run source ~/.zshrc. You should now see the default Starship prompt. However, the default look is just the beginning.

Step 2: Configuring Your Prompt

Starship is configured via a TOML file located at ~/.config/starship.toml. If the file doesn’t exist, you’ll need to create it. This is where the real magic happens.

I prefer a minimal layout that only shows information when it’s relevant. For example, I only want to see the Node.js version if I’m actually inside a project with a package.json. Here is my recommended starter configuration:

# ~/.config/starship.toml

# Move the prompt to a new line for more space
add_newline = true

[character]
success_symbol = "[➜](bold green)"
error_symbol = "[➜](bold red)"

[git_branch]
symbol = "branch "
style = "bold purple"

[package]
disabled = true # I prefer seeing the specific language version instead

[nodejs]
symbol = " "
style = "bold blue"

As shown in the image below, the difference between a default prompt and a configured one is an immediate boost in situational awareness. You can see exactly which Git branch you’re on and which runtime version is active without typing node -v every five minutes.

Comparison of default terminal prompt vs customized Starship prompt showing Git and Node.js modules

Step 3: Advanced Customization and Presets

If you don’t want to write TOML from scratch, Starship offers official presets. You can browse them on their website or apply them via the CLI. For instance, if you love the “Pure” prompt style, you can apply it instantly.

One thing I’ve noticed in my experience is that as you add more modules to your prompt, the shell startup might feel slightly heavier. While Starship is fast, the way your shell initializes can still be a bottleneck. If you notice a lag, I highly recommend reading my guide on how to speed up zsh startup to ensure your environment remains snappy.

Pro Tips for Starship Power Users

Conditional Modules: Use the disabled = true flag for modules you rarely use to keep the prompt clean.
Custom Symbols: You can replace any symbol with any character from your Nerd Font. Use a tool like gucharmap or a cheat sheet to find cool icons.
Transient Prompt: If you use Zsh, look into transient prompts. This keeps your terminal history clean by hiding the full prompt of previous commands.

Troubleshooting Common Issues

“I see weird boxes instead of icons!”

This is the most common issue. It means your terminal emulator is not using a Nerd Font. Go to your terminal settings (e.g., iTerm2 → Preferences → Profiles → Text) and ensure the font is set to a “Nerd Font” variant.

“My prompt is lagging on large Git repos”

Even with Rust, very massive repositories can cause a slight delay. You can disable the git status check for specific folders by adding them to your .gitignore or using the starship.toml git settings to disable specific features like ignore_submodules = true.

What’s Next?

Now that your prompt is optimized, why not optimize the rest of your workflow? I suggest looking into zoxide for smarter directory jumping or fzf for fuzzy finding. Combining these with Starship creates a truly modern development environment.

If you found this starship prompt tutorial helpful, consider subscribing to my newsletter for more automation and productivity tips!