tools-only Shell Prompt Troubleshooting
Common issues and solutions for Powerlevel10k and Starship.
Quick Diagnostics
Check Current Setup
# What shell?
echo $SHELL
echo $ZSH_VERSION
# What prompt?
echo $ZSH_THEME # P10k via OMZ
which starship # Starship installed?
# P10k status
[[ -f ~/.p10k.zsh ]] && echo "P10k config exists"
# Starship status
[[ -f ~/.config/starship.toml ]] && echo "Starship config exists"
Timing Analysis
# Shell startup time
time zsh -i -c exit
# Starship module timing
starship timings
# P10k profiling (add to .zshrc)
zmodload zsh/zprof
# Then at end:
zprof
Powerlevel10k Issues
Icons/Glyphs Not Displaying
Symptom: Boxes, question marks, or missing icons
Solution 1: Install Nerd Font
# macOS
brew tap homebrew/cask-fonts
brew install --cask font-meslo-lg-nerd-font
# Or download manually from
# https://github.com/ryanoasis/nerd-fonts/releases
Solution 2: Configure Terminal
- Open terminal preferences
- Set font to "MesloLGS NF" or installed Nerd Font
- Restart terminal
Solution 3: Use ASCII-only mode
# Re-run wizard with "no" to font questions
p10k configure
Instant Prompt Errors
Symptom: Warnings about console output during instant prompt
Solution 1: Move output above instant prompt block
# This BEFORE instant prompt:
echo "Welcome!"
# Instant prompt block
if [[ -r "${XDG_CACHE_HOME:-$HOME/.cache}/p10k-instant-prompt-${(%):-%n}.zsh" ]]; then
source "${XDG_CACHE_HOME:-$HOME/.cache}/p10k-instant-prompt-${(%):-%n}.zsh"
fi
# Everything else AFTER
Solution 2: Suppress warnings
# In ~/.p10k.zsh
typeset -g POWERLEVEL9K_INSTANT_PROMPT=quiet
Solution 3: Disable instant prompt
# In ~/.p10k.zsh
typeset -g POWERLEVEL9K_INSTANT_PROMPT=off
gitstatus Failed to Initialize
Symptom: [ERROR]: gitstatus failed to initialize
Solution 1: Clear cache
rm -rf ~/.cache/gitstatus
exec zsh
Solution 2: Manual binary install
# Check architecture
uname -m
# Download appropriate binary from
# https://github.com/romkatv/gitstatus/releases
# Place in ~/.cache/gitstatus/
Solution 3: Build from source
git clone --depth=1 https://github.com/romkatv/gitstatus.git
cd gitstatus
./build -w
Slow in Git Repositories
Symptom: Prompt freezes when entering repo
Solution 1: Reduce dirty check threshold
# ~/.p10k.zsh
typeset -g POWERLEVEL9K_VCS_MAX_INDEX_SIZE_DIRTY=100
Solution 2: Disable dirty check
typeset -g POWERLEVEL9K_VCS_MAX_INDEX_SIZE_DIRTY=-1
Solution 3: Disable git entirely
typeset -g POWERLEVEL9K_DISABLE_GITSTATUS=true
Theme Not Loading
Symptom: Default zsh prompt instead of P10k
Check 1: Theme path
ls ${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/themes/powerlevel10k
Check 2: .zshrc setting
grep ZSH_THEME ~/.zshrc
# Should be: ZSH_THEME="powerlevel10k/powerlevel10k"
Check 3: Oh My Zsh loading
grep "source.*oh-my-zsh.sh" ~/.zshrc
Solution: Reinstall
rm -rf ${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/themes/powerlevel10k
git clone --depth=1 https://github.com/romkatv/powerlevel10k.git \
${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/themes/powerlevel10k
exec zsh
Configuration Wizard Issues
Symptom: p10k configure doesn't work
Solution 1: Source manually
source ~/.oh-my-zsh/custom/themes/powerlevel10k/powerlevel10k.zsh-theme
p10k configure
Solution 2: Reset config
rm ~/.p10k.zsh
exec zsh
# Wizard should start automatically
Starship Issues
Prompt Not Showing
Symptom: Default shell prompt instead of Starship
Check 1: Installation
which starship
starship --version
Check 2: Shell integration
# Zsh
grep starship ~/.zshrc
# Should have: eval "$(starship init zsh)"
# Bash
grep starship ~/.bashrc
Solution: Add integration
# ~/.zshrc
eval "$(starship init zsh)"
Git Status Timeout
Symptom: [WARN] - Executing command "/usr/bin/git" timed out
Solution 1: Increase timeout
# ~/.config/starship.toml
command_timeout = 2000 # 2 seconds
Solution 2: Disable git_status
[git_status]
disabled = true
Solution 3: Optimize git
# For very large repos
git config core.untrackedCache true
git config core.fsmonitor true
Module Not Appearing
Symptom: Expected module missing from prompt
Check 1: Detection files
# Show what Starship detects
starship explain
Check 2: Module disabled
# Check if disabled in config
[python]
disabled = false # Make sure this isn't true
Solution: Force detection
[python]
detect_files = []
detect_folders = []
detect_extensions = []
python_binary = ["python3", "python"]
disabled = false
Slow Prompt
Symptom: Noticeable delay after each command
Step 1: Identify slow module
starship timings
Step 2: Disable culprit
# If git_status is slow
[git_status]
disabled = true
# If python detection is slow
[python]
disabled = true
Config Not Loading
Symptom: Changes to starship.toml have no effect
Check 1: Config location
echo $STARSHIP_CONFIG
ls ~/.config/starship.toml
Check 2: TOML syntax
# Validate TOML
starship config # Will error on invalid syntax
Solution: Specify config path
export STARSHIP_CONFIG=~/.config/starship.toml
Wrong Version Detected
Symptom: Shows wrong Python/Node/etc. version
Solution 1: Specify binary path
[python]
python_binary = ["/usr/local/bin/python3", "python3"]
Solution 2: Check PATH order
which python
which -a python # All in PATH
General Issues
Prompt Appears Twice
Symptom: Duplicate prompts displayed
Cause: Multiple prompt initializations
Solution: Check for duplicate init calls
grep -E "(p10k|starship)" ~/.zshrc
# Remove duplicates
Colors Wrong
Symptom: Incorrect or missing colors
Check 1: Terminal color support
echo $TERM
# Should be xterm-256color or similar
Check 2: COLORTERM
echo $COLORTERM
# Should be truecolor for full support
Solution: Set terminal type
# ~/.zshrc
export TERM=xterm-256color
export COLORTERM=truecolor
SSH Breaks Prompt
Symptom: Prompt works locally but not over SSH
Check 1: TERM forwarding
ssh -t user@host 'echo $TERM'
Solution 1: Set TERM on remote
# Remote ~/.zshrc
export TERM=xterm-256color
Solution 2: Configure SSH
# ~/.ssh/config
Host *
SetEnv TERM=xterm-256color
tmux/screen Issues
Symptom: Prompt breaks in tmux
Solution 1: tmux term setting
# ~/.tmux.conf
set -g default-terminal "screen-256color"
set -ga terminal-overrides ",xterm-256color:Tc"
Solution 2: Force shell
# ~/.tmux.conf
set -g default-shell /bin/zsh
Recovery Procedures
Reset to Default Prompt
Zsh without frameworks:
# Minimal .zshrc
PROMPT='%n@%m:%~%# '
With Oh My Zsh:
# In .zshrc
ZSH_THEME="robbyrussell"
Complete P10k Reset
# Remove all P10k files
rm -rf ~/.p10k.zsh
rm -rf ~/.cache/p10k-*
rm -rf ~/.cache/gitstatus
# Reinstall
rm -rf ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/themes/powerlevel10k
git clone --depth=1 https://github.com/romkatv/powerlevel10k.git \
${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/themes/powerlevel10k
exec zsh
Complete Starship Reset
# Remove config
rm ~/.config/starship.toml
# Remove from shell
# Edit ~/.zshrc and remove: eval "$(starship init zsh)"
# Uninstall
brew uninstall starship
# or
rm $(which starship)
exec zsh
Getting Help
Powerlevel10k
- GitHub Issues: https://github.com/romkatv/powerlevel10k/issues
- Note: Maintainer no longer responding (project on life support)
- Search existing issues for solutions
Starship
- GitHub Discussions: https://github.com/starship/starship/discussions
- GitHub Issues: https://github.com/starship/starship/issues
- Discord: https://discord.gg/starship
Debug Information to Collect
# System info
uname -a
echo $SHELL
echo $ZSH_VERSION
echo $TERM
# P10k
cat ~/.p10k.zsh | head -50
ls -la ~/.cache/gitstatus/
# Starship
starship --version
cat ~/.config/starship.toml
starship timings
starship explain