Ultimate Manual – Customizing the Bash Prompt on Ubuntu with Starship + Nerd Fonts

1. Why Spend Time on Your Prompt?

2. Prerequisites – What You Need on Ubuntu

NOTE: This guide assumes a pure Bash environment (no Oh‑My‑Bash, no PS1 hacks). If you already use a Bash framework, you can still follow the steps – just make sure to comment out the old PS1 assignments.

3. Step‑by‑Step: Install a Nerd Font

Nerd Fonts are patched fonts that embed thousands of icons (Font Awesome, Octicons, Powerline, etc.) used by Starship.

3.1 Choose a Font

3.2 Download & Install

You can install via the fonts-noto-color-emoji package or manually.

Method A – Using apt (Ubuntu 22.04+)

# Install the pre‑packaged Nerd Font from the Ubuntu repo (limited selection)
sudo apt update
sudo apt install fonts-firacode
# For the Nerd‑patched version:
sudo apt install fonts-firacode-nerd

The repo version may be outdated. For the latest glyph set, use Method B.

Method B – Manual download (recommended)

# Choose a version, e.g., JetBrainsMono
FONT_NAME="JetBrainsMono"
VERSION="2.304"   # check https://github.com/ryanoasis/nerd-fonts/releases for latest

mkdir -p ~/.local/share/fonts/nerd-fonts
cd ~/.local/share/fonts/nerd-fonts

wget "https://github.com/ryanoasis/nerd-fonts/releases/download/v${VERSION}/${FONT_NAME}.zip"
unzip "${FONT_NAME}.zip"
rm "${FONT_NAME}.zip"

# Update the font cache
fc-cache -fv

3.3 Set the Font in Your Terminal Emulator

Tip: Enable “Allow bold text” and “Use built‑in rendering for Powerline symbols” if your emulator offers those options.

4. Step‑by‑STEP: Install & Configure Starship

4.1 What is Starship?

Starship is a cross‑shell, minimal, fast prompt written in Rust. It reads a single starship.toml file and prints a line of ANSI‑colored text that Bash (or any shell) can use as PS1.

4.2 Install the Binary

# Using the official script (recommended)
curl -fsSL https://starship.rs/install.sh | bash

# Or via Cargo (if you already have Rust)
cargo install starship

# Verify
starship --version

The installer puts the binary at ~/.cargo/bin/starship. Add it to your PATH if it isn’t already:

echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

4.3 Verify Execution

starship prompt
# Should output a short colored line (the prompt itself)

If you see command not found, double‑check the PATH entry and re‑source.

5. Integrating Starship with Bash

Open (or create) ~/.bashrc and add the following near the end before any custom PS1:

# -------------------------------------------------
# Starship Prompt – Begin
# -------------------------------------------------
# Load the Starship binary and initialise the prompt.
# The eval command is required because Starship prints a
# string that contains escape sequences.
if command -v starship > /dev/null; then
    # Optional: make Starship load faster by disabling certain modules here
    # export STARSHIP_CONFIG="$HOME/.config/starship.toml"
    eval "$(starship init bash)"
fi
# -------------------------------------------------
# Starship Prompt – End
# -------------------------------------------------

5.1 Reload

source ~/.bashrc

You should now see a very minimal prompt (just a line of a symbol). The rest of this manual will teach you how to make it useful and beautiful.

6. Deep‑Dive: The starship.toml Configuration File

Starship reads its configuration from $XDG_CONFIG_HOME/starship.toml (by default ~/.config/starship.toml). This file is fully TOML‑syntax and controls every module that appears in the prompt.

6.1 File Skeleton

# ~/.config/starship.toml

# -------------------------------------------------
# Global Settings
# -------------------------------------------------
[character]                # The prompt "character"
success_symbol = "[❯](bold green)"          # When the last command succeeded
error_symbol   = "[❯](bold red)"            # When the last command failed
vicmd_symbol   = "[❮](bold bright-black)"  # When in vi insert mode (if using vi mode)

[cmd_duration]             # Show how long the previous command ran
min_time = 2_000            # Show only if >2s (milliseconds)

[hostname]                 # Optional: show hostname on remote connections
ssh_only = true
format = "[$ssh_symbol]($style) [$hostname]($style) "

# -------------------------------------------------
# Git Section
# -------------------------------------------------
[git_branch]
symbol = "🌿 "               # Nerd Font branch icon
format = "[$symbol$branch]($style) "

[git_state]
rebase = "REBASING"
merge = "MERGING"
format = "[$state]($style) "

[git_status]
# Shows staged, unstaged, untracked, conflicted, etc.
format = "[$all_status]($style) "
conflicted = "⚔️"
ahead = "⇡${count}"
behind = "⇣${count}"
staged = "✚${count}"
unstaged = "✚${count}"
untracked = "…"

# -------------------------------------------------
# Language Runtimes
# -------------------------------------------------
[python]
symbol = "🐍 "
style = "bright-yellow"
format = "[$symbol($virtualenv)]($style) "

[nodejs]
symbol = "⚡ "
format = "[$symbol$v]($style) "

[golang]
symbol = "🐹 "
format = "[$symbol($version )]($style) "

# -------------------------------------------------
# Miscellaneous
# -------------------------------------------------
[time]
disabled = false
format = "[$time]($style) "
time_format = "%R"   # 24‑hour HH:MM

[status]
disabled = false
format = "[$symbol $status]($style) "

[custom.k8s]
command = "kubectl config current-context 2>/dev/null || echo ''"
when = "kubectl config current-context 2>/dev/null"
symbol = "⎈ "
style = "cyan"
format = "[$symbol($output)]($style) "

# -------------------------------------------------
# Palette – define colors once and reuse
# -------------------------------------------------
[palettes]
# Define a palette to avoid duplication
my_palette = { 
    primary = "bright-blue",
    secondary = "bright-black",
    success = "green",
    error = "red",
    warning = "yellow"
}

Tip: Use the starship explain command to get a JSON view of each module's default values.

6.2 Common Global Settings

6.3 Understanding format Syntax

• ${module} – a placeholder for a module defined elsewhere ([git_branch], [nodejs], etc.).
• Literal text may be placed directly: "on " or " 🔧 ".
• Colors can be added inline with ($style) or via a named palette: ($my_palette.success).

Example – a compact dev‑focused layout:

format = """
[┌](bold bright-black)$username$hostname $directory
[│](bold bright-black)$git_branch$git_status$python$nodejs$golang$kubernetes
[└](bold bright-black)$character
"""

The three‑line layout mimics Powerline but uses pure Unicode characters (╭─, │, ╰─) – you can replace them with Nerd‑Font glyphs (\ue0b0, \ue0b2, etc.) for a sleek look.

7. Common Modules & How to Tweak Them

Below is a module‑by‑module cheat sheet for developers. Each block shows the default values, typical customizations, and why you might want to change them.

7.1 Example: A “Powerline‑Style” format

format = """
[╭─](bold $palette.primary)$username$hostname $directory
[│](bold $palette.primary)$git_branch$git_status$python$nodejs$golang$kubernetes
[╰─](bold $palette.primary)$character
"""

How it works

• The first line shows user/host and directory, prefixed by a Unicode “╭─”.
• The second line prints git information and language runtimes.
• The third line is the final prompt character.

Result (colors omitted for brevity):

╭─john@work ~/projects/starship-demo
│  main ⇡2 ⇣1  (venv)  1.22.5 ⎈ dev-cluster
╰─❯

8. Adding Your Own Custom Modules

Starship’s [custom.<name>] section lets you run any command and display its output, with conditions for when it should appear.

8.1 Anatomy of a Custom Module

8.2 Real‑World Examples

8.2.1 Docker Context

[custom.docker]
command = "docker context show 2>/dev/null || echo ''"
when = "docker context show 2>/dev/null"
symbol = "🐳 "
style = "cyan"
format = "[$symbol($output)]($style) "

8.2.2 Terraform Workspace

[custom.terraform]
command = "terraform workspace show 2>/dev/null"
when = "test -d .terraform"
symbol = "🛠️ "
style = "bright-yellow"
format = "[$symbol($output)]($style) "

8.2.3 AWS Profile

[custom.aws]
command = "aws configure get profile"
when = "aws configure get profile"
symbol = "☁️ "
style = "bright-blue"
format = "[$symbol($output)]($style) "

8.2.4 Battery Status (Linux)

[custom.battery]
command = "cat /sys/class/power_supply/BAT0/capacity"
when = "test -d /sys/class/power_supply/BAT0"
symbol = "🔋"
style = "green"
format = "[$symbol $output%]($style) "

Tip: Keep custom commands fast. Prefer reading a file (e.g., /proc/...) over spawning heavy CLI tools.

8.3 Debugging

# Use Starship's built‑in debug mode
starship explain
 Here's a breakdown of your prompt:
 "❯ " (<1ms)              -  A character (usually an arrow) beside where the text is entered in your terminal
 " 󰋞  " (<1ms)            -  The current working directory
 "@192.168.1.14 " (<1ms)  -  The currently assigned ipv4 address
 "   " (11ms)            -  The current operating system
 "  21:08 " (<1ms)       -  The current local time
 " pavel " (<1ms)         -  The active user's username

This prints a JSON object showing why the module was rendered or why it was skipped (missing file, timeout, etc.).

9. Color Schemes, Transparency & True‑Color

9.1 256‑Color vs True‑Color

• 256‑color works everywhere (including older xterm). Use codes like bright-red, 247, #ff5f00.
• True‑color (24‑bit) offers unlimited palette (#ff00ff). Most modern terminals (GNOME Terminal, Alacritty, Kitty, iTerm2) support it.

Starship automatically detects true‑color. You can force a mode:

[palette]
# Force 256‑color mode (useful for remote SSH to an old box)
# use_256_colors = true

9.2 Sample Palettes

Define a palette in starship.toml:

[palettes.dracula]
primary = "#ff79c6"
secondary = "#6272a4"
accent = "#bd93f9"
error = "#ff5555"
warning = "#f1fa8c"
success = "#50fa7b"

Then reference it:

[character]
success_symbol = "[❯]($dracula.success bold)"
error_symbol = "[❯]($dracula.error bold)"

9.3 Transparent Background

Most terminals respect the background of the terminal window. If you use a transparent terminal, Starship’s colors will blend nicely. Just ensure you don’t set a background color in any module:

[character]
background = "none"

If a module accidentally sets a background, you can override globally:

[custom]
background = "none"

10. Performance Optimizations

Example: Global Fast‑Prompt Settings

# ~/.config/starship.toml
scan_timeout = 10
command_timeout = 500
add_newline = false
[git_status]
disabled = false
ignore_submodules = true
ignore_stash = true

11. Fallback & Compatibility

11.1 When Starship Can’t Load (e.g., Remote Minimal Box)

1. Graceful degradation – Create a minimal starship.toml in ~/.config/starship.toml that only enables character and directory.

Detect missing binary – In ~/.bashrc:

if ! command -v starship &>/dev/null; then
    export PS1='\u@\h:\w\$ '
else
    eval "$(starship init bash)"
fi

11.2 Using Starship with Other Shells

• Zsh: eval "$(starship init zsh)" in ~/.zshrc.
• Fish: starship init fish | source.

All modules share the same config file, so you get a consistent look across shells.

11.3 Mixing with Oh‑My‑Bash / Bash‑It

If you already use a framework that sets PS1, you can either:

• Disable the framework’s prompt (export OMB_PROMPT=off for Oh‑My‑Bash) and let Starship own the prompt.
• Or wrap Starship inside the framework by calling starship prompt inside a custom segment.

12. Troubleshooting FAQ

13. Advanced Topics

13.1 Git Hooks to Speed Up Prompt

You can configure Git to cache status in a hidden file, reducing Starship’s scanning cost:

git config --global status.showUntrackedFiles no   # hide untracked files
git config --global core.preloadIndex true        # preload the index
git config --global gc.auto 0                     # disable auto‑gc in hot repos

13.2 Using Starship in CI (e.g., GitHub Actions)

When you run tests that log the prompt (rare), you might want a non‑interactive prompt:

steps:
  - name: Install Starship
    run: |
      curl -fsSL https://starship.rs/install.sh | bash
      echo 'eval "$(starship init bash)"' >> $HOME/.bashrc
  - name: Run script
    run: |
      source $HOME/.bashrc
      starship prompt   # prints the prompt string

Set add_newline = false for compact CI logs.

13.3 Multi‑Line Right‑Aligned Prompt

Starship can output a right‑aligned segment if your terminal supports it (\e[?7l / \e[?7h tricks).

right_format = "$time"

To make the right side appear on the same line (like Powerline), ensure your terminal supports the OSC 133 escape sequences (most modern terminals do). No extra config needed.

14. Resources, Cheat‑Sheets & Community

Congratulations!

You now have a fully‑featured, fast, beautiful, and cross‑shell prompt powered by Starship and Nerd Fonts. Feel free to tweak the modules, symbols, and colors until the prompt feels like an extension of your workflow.

Happy hacking! 🚀