Customize the ZSH Prompt in macOS: A Complete Guide

Introduction: Why Customize Your Prompt?

The command-line prompt (prompt) is the first thing you see in the terminal. The default ZSH prompt on macOS (%) is functional but uninformative and visually sparse. Customization allows you to:

• Increase productivity: Immediately see the current path, Git status (branch, changes), and time.
• Improve readability: Use colors to separate elements.
• Personalize your environment: Make the terminal your own, which is especially important for daily work.

After completing this guide, you will have an informative and stylish prompt tailored to your tasks.

Requirements / Preparation

1. Operating System: macOS (any modern version supporting ZSH).
2. Shell: ZSH must be installed and active. macOS Catalina (10.15) and newer use ZSH by default.
3. Permissions: Write access to your user's home directory (~).
4. (Optional) Oh My Zsh: If you want to use ready-made themes, install Oh My Zsh. Installation instructions are available in our guide /guides/macos/install-oh-my-zsh.

Step-by-Step Instructions

Step 1: Check if ZSH is the Default Shell

Open the Terminal application. Enter the command:

echo $SHELL

If the output is /bin/zsh or /usr/local/bin/zsh, you are using ZSH. If you see /bin/bash or another path, change your shell:

chsh -s /bin/zsh

You will need to enter your password. After that, close and reopen the Terminal window.

Step 2: Open and Back Up the .zshrc File

The main ZSH configuration file is ~/.zshrc. It may not exist in a fresh installation.

1. Check for its existence:

   ls -la ~/.zshrc
   

2. If the file exists, create a backup (it's simple and safe):

   cp ~/.zshrc ~/.zshrc.backup.$(date +%Y%m%d)
   

   This command creates a copy with a date in the name, e.g., .zshrc.backup.20260216.
3. If the file does not exist, create an empty one:

   touch ~/.zshrc
   

4. Open the file in a text editor. For simplicity, use nano:

   nano ~/.zshrc
   

Step 3: Choose and Install a Prompt Theme (if using Oh My Zsh)

If you have Oh My Zsh installed, this is the fastest way to get a nice prompt.

1. In the opened ~/.zshrc file, find the line starting with ZSH_THEME. It usually looks like this:

   ZSH_THEME="robbyrussell"
   

2. Change the value to the name of the desired theme. Popular options:
   • agnoster — compact, with Git information and last command status.
   • avit — shows time, path, Git branch.
   • bira — colorful, with lots of information.
   • lambda — minimalist, with a λ symbol.
3. The full list of built-in themes is in the directory: /usr/share/oh-my-zsh/themes/. You can list them with:

   ls /usr/share/oh-my-zsh/themes/ | sed 's/.zsh-theme//'
   

4. Save the file in nano (Ctrl+X, then Y, then Enter) and apply the changes:

   source ~/.zshrc
   

   Your prompt should change instantly.

Step 4: Configure a Custom Prompt Manually (without Oh My Zsh or for Fine-Tuning)

If you are not using Oh My Zsh or want full control, configure the PROMPT (main prompt) and RPROMPT (right prompt) variables.

1. In the ~/.zshrc file, add or modify the line with PROMPT. Here are a few examples:
   Simple prompt with path and symbol:

   PROMPT='%F{blue}%~%f %# '
   

   • %F{blue} — start in blue color.
   • %~ — current working directory, shortened to ~ for the home folder.
   • %f — reset color.
   • %# — symbol # for root, % for a regular user.
   
   Prompt with user, host, and time:

   PROMPT='%F{green}%n%f@%F{magenta}%m%f %F{cyan}%~%f %F{yellow}%*%f %# '
   

   • %n — username.
   • %m — hostname (machine).
   • %* — current time in HH:MM:SS format.
2. For the right prompt (RPROMPT), use similar escape sequences. It aligns to the right edge:

   RPROMPT='%F{red}%?%f' # Shows the exit code of the last command (0 - green, !=0 - red)
   

3. Save the file and run source ~/.zshrc.

Step 5: Add Informative Elements (Git, Command Status)

A powerful prompt often shows Git status. In 'vanilla' ZSH, this requires a custom function.

1. Add a function to ~/.zshrc to display Git information:

   # Function to display Git information in the prompt
   git_prompt_info() {
     local ref
     ref=$(git symbolic-ref HEAD 2> /dev/null) || return
     echo " (%F{magenta}${ref#refs/heads/}%f)"
   }
   

   
   This function shows the current branch in magenta inside parentheses.
2. Integrate it into PROMPT:

   PROMPT='%F{green}%n@%m%f %F{cyan}%~%f$(git_prompt_info) %# '
   

   
   Now, when inside a Git repository directory, you will see the branch.
3. For more complex status (changed files, ahead/behind), it's better to use a ready-made implementation from Oh My Zsh or third-party scripts. If Oh My Zsh is installed, you can simply add to ~/.zshrc:

   autoload -Uz vcs_info
   precmd_vcs_info() { vcs_info }
   precmd_functions+=( precmd_vcs_info )
   setopt prompt_subst
   RPROMPT=\$vcs_info_msg_0_
   

   
   And configure zstyle for vcs_info. This is a more advanced method.

Step 6: Apply Changes and Test

1. After each change to ~/.zshrc, apply it:

   source ~/.zshrc
   

2. Test the prompt:
   • Navigate to different directories (cd /, cd ~/Documents), ensure the path (%~) updates correctly.
   • If you added Git, go into any Git repository and make a few commits/changes, check that the branch and status are displayed.
   • Check colors. If colors do not display, ensure your terminal supports a 256-color palette (this is the default in macOS Terminal).
3. If something goes wrong, restore the backup:

   cp ~/.zshrc.backup.20260216 ~/.zshrc
   source ~/.zshrc
   

   (replace the date with yours).

Verification

Successful prompt configuration means:

1. When opening a new Terminal window or tab, your custom prompt is displayed.
2. The path in the prompt updates correctly when changing directories.
3. (If configured) Git information appears only inside repositories and reflects the current branch.
4. Colors display properly, and the text is readable.
5. The prompt does not produce ZSH syntax errors (no messages like zsh: event not found when typing commands).

Troubleshooting

Problem: Colors in the prompt display as strange symbols or do not work.

Solution: Ensure you are using the correct escape codes (%F{color}, %f). Instead of %F{blue}, you can use a numeric code: %F{4}. Also, check your terminal settings: in macOS Terminal, under Preferences -> Profiles -> Text, ensure "Use built-in ANSI color set" or "Use bright colors for bold text" is enabled.

Problem: The git_prompt_info function does not work, showing emptiness even inside a Git repository.

Solution: Ensure you are in the root of the repository (where the .git directory exists). The function looks for this directory. Also, check for typos in the function name. For debugging, add set -x before the function call and set +x after in ~/.zshrc to see what is happening.

Problem: The prompt "breaks" (wraps prompt symbols to a new line) with a long path.

Solution: ZSH automatically wraps long prompts, but this can look messy. Use the PROMPT_EOL_MARK parameter or wrap long parts in %{%} for correct length calculation. For example: PROMPT='%{%F{blue}%}%~%{%f%} %# '. A more robust solution is to use the zsh-autosuggestions or powerlevel10k plugin, which manage space intelligently.

Problem: After configuring the prompt, other settings in .zshrc (aliases, path) stopped working.

Solution: You likely accidentally deleted or commented out other lines in the file. Restore the file from your backup and make changes more carefully, adding new lines at the end of the file or before relevant sections without removing existing content.