Guide for ~/.zshrc

The ~/.zshrc file is a shell script that runs every time you open a new interactive Zsh session. It's where you configure your terminal environment: aliases, functions, environment variables, prompt, plugins, and more.

Location and editing

The file lives at ~/.zshrc. Open it in any text editor:

nano ~/.zshrc
# or
code ~/.zshrc

After saving changes, reload the file without restarting the terminal:

source ~/.zshrc

Structure

A typical ~/.zshrc is organized into sections. Order matters in some cases — for example, $PATH should be set before anything that depends on it.

# 1. Environment variables
# 2. PATH
# 3. Oh My Zsh (if used)
# 4. Plugins
# 5. Aliases
# 6. Functions
# 7. Prompt / theme
# 8. Tool initializations (nvm, pyenv, etc.)

Environment variables

Variables that configure your shell and tools:

export EDITOR="nano"               # Default text editor
export LANG="en_US.UTF-8"         # Locale
export TERM="xterm-256color"      # Terminal color support

PATH

$PATH tells the shell where to look for executables. Prepend custom directories so they take priority:

export PATH="$HOME/.local/bin:$PATH"
export PATH="/opt/homebrew/bin:$PATH"   # Apple Silicon Homebrew

Always append $PATH at the end to preserve existing entries.

Aliases

Aliases are shorthand for longer commands:

# Navigation
alias ..="cd .."
alias ...="cd ../.."
alias ~="cd ~"

# Listings
alias ls="ls --color=auto"
alias ll="ls -lah"

# Git
alias gs="git status"
alias ga="git add"
alias gc="git commit"
alias gp="git push"

# Safety nets
alias rm="rm -i"
alias cp="cp -i"
alias mv="mv -i"

Functions

Functions handle logic that aliases can't — arguments, conditionals, loops:

# Create a directory and cd into it
mkcd() {
  mkdir -p "$1" && cd "$1"
}

# Extract any archive
extract() {
  case "$1" in
    *.tar.gz)  tar -xzf "$1" ;;
    *.tar.bz2) tar -xjf "$1" ;;
    *.zip)     unzip "$1" ;;
    *.gz)      gunzip "$1" ;;
    *.rar)     unrar x "$1" ;;
    *)         echo "Unknown format: $1" ;;
  esac
}

Oh My Zsh

If you use Oh My Zsh, its configuration block typically sits near the top:

export ZSH="$HOME/.oh-my-zsh"
ZSH_THEME="robbyrussell"

plugins=(git z zsh-autosuggestions zsh-syntax-highlighting)

source $ZSH/oh-my-zsh.sh

See the Oh My Zsh documentation for the full list of built-in plugins.

Prompt (without Oh My Zsh)

If you manage the prompt manually, set $PROMPT or $PS1:

PROMPT="%F{cyan}%n@%m%f %F{yellow}%~%f %# "

Common prompt escape codes:

Code	Output
%n	Username
%m	Hostname
%~	Current directory (shortened)
%#	# for root, % otherwise
%F{color}	Start foreground color
%f	Reset color

History

Control how Zsh stores and searches command history:

HISTFILE="$HOME/.zsh_history"
HISTSIZE=10000
SAVEHIST=10000

setopt HIST_IGNORE_DUPS       # Don't store duplicate commands
setopt HIST_IGNORE_SPACE      # Don't store commands prefixed with a space
setopt SHARE_HISTORY          # Share history across all open sessions
setopt APPEND_HISTORY         # Append rather than overwrite the history file

Prefix any command with a space to keep it out of history — useful for commands with passwords or tokens.

Key bindings

bindkey "^[[A" history-search-backward   # Up arrow: search history
bindkey "^[[B" history-search-forward    # Down arrow: search history

Tool initializations

Many tools inject initialization code into ~/.zshrc automatically. These usually go at the bottom:

# nvm (Node Version Manager)
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

# pyenv (Python Version Manager)
export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"

# rbenv (Ruby Version Manager)
eval "$(rbenv init - zsh)"

# Homebrew
eval "$(/opt/homebrew/bin/brew shellenv)"

Sourcing other files

Keep your ~/.zshrc tidy by splitting it into separate files and sourcing them:

source "$HOME/.zsh_aliases"
source "$HOME/.zsh_functions"
[ -f "$HOME/.zshrc.local" ] && source "$HOME/.zshrc.local"

The [ -f ... ] check prevents errors if the file doesn't exist — handy for machine-specific config that may not be present everywhere.

Debugging

If your shell is slow to start or throwing errors, identify the culprit:

# Time how long startup takes
time zsh -i -c exit

# Trace every command executed during startup
zsh -x

Comment out sections of ~/.zshrc one at a time to narrow down the source of an issue.

Quick reference

Task	Command
Edit ~/.zshrc	nano ~/.zshrc or code ~/.zshrc
Reload without restarting	source ~/.zshrc
Print an environment variable	echo $VARIABLE
List all aliases	alias
List all functions	functions
Check where a command comes from	which <command> or type <command>
Time shell startup	time zsh -i -c exit