Shell Initialisation & Loading Order¶

This page explains which shell config files run when, and why. Understanding this is essential for knowing where to put environment variables, aliases, and tool initialisations — and for debugging "command not found" issues.

For how this repo uses these concepts, see the Repository Mapping and Shell Modules pages.

Shell Types¶

Shells have two independent properties — login vs non-login and interactive vs non-interactive — that combine:

The key distinction: macOS terminals default to login + interactive (every new window), while Linux terminals default to non-login + interactive (login happened at GDM/SDDM). This affects which config files are read.

Zsh Loading Order¶

This repo uses zsh as the primary shell. The loading order determines where to put things:

Each user file has a system-wide counterpart (/etc/zshenv, /etc/zprofile, /etc/zshrc, /etc/zlogin) that runs before the user file.

Loading sequences:

• Login Shell (macOS default):

  • /etc/zshenv → ~/.zshenv → /etc/zprofile → ~/.zprofile → /etc/zshrc → ~/.zshrc → /etc/zlogin → ~/.zlogin

• Interactive Non-Login Shell (Linux terminal default):

  • /etc/zshenv → ~/.zshenv → /etc/zshrc → ~/.zshrc

• Script (Non-Interactive):

  • /etc/zshenv → ~/.zshenv

Load Guard Pattern¶

Because ~/.zshenv runs for every zsh invocation (including subshells and scripts), it should use a guard variable to avoid redundant work:

# Prevent double loading in subshells that inherit the environment
if [[ -n "$__ZSHENV_LOADED" ]]; then
  return
fi
export __ZSHENV_LOADED=1

The return statement is safe here because ~/.zshenv is always sourced (never executed directly), so return exits the sourced file without terminating the shell.

Bash Loading Order¶

Included for reference — this repo uses zsh, but understanding bash loading is useful for debugging scripts and login shells.

Loading sequences:

• Login Shell (macOS default):

  • /etc/profile → first of ~/.bash_profile / ~/.bash_login / ~/.profile

• Interactive Non-Login Shell (Linux terminal default):

  • /etc/bash.bashrc → ~/.bashrc

• Script (Non-Interactive): $BASH_ENV (if set, sources the file it points to; otherwise nothing)

Note: Bash login shells do not read ~/.bashrc by default. Most users source ~/.bashrc inside their ~/.bash_profile to ensure consistency.

macOS vs. Linux¶

macOS¶

• macOS terminals (Terminal.app, iTerm2, Ghostty) launch every new window as a login shell.
• This means ~/.zprofile and ~/.zshrc are both read for every window.
• path_helper: macOS runs /usr/libexec/path_helper from /etc/zprofile (since Catalina, when zsh became the default shell). It reads /etc/paths and /etc/paths.d/*, builds a PATH with system paths first, then appends any existing PATH entries. The effect: Homebrew bins that ~/.zshenv placed at the front of $PATH get pushed behind /usr/bin, /bin, etc.
• How the dotfiles handle this: ~/.zshenv sets up Homebrew via brew shellenv (essential for non-login shells and scripts, which never see /etc/zprofile). For login shells, ~/.zprofile re-runs brew shellenv — it fires after /etc/zprofile, so its prepend wins over path_helper's reorder. The duplication is intentional: each copy serves a different shell type. See the comment block at the top of home/dot_zprofile.tmpl for the canonical explanation alongside the implementation.

Linux¶

• Desktop environments (GNOME, KDE) treat the session login as the login shell. Terminal windows start non-login + interactive shells.
• This means ~/.zprofile is skipped for terminal sessions, and many display managers source ~/.profile but not ~/.zprofile. This is why environment variables belong in ~/.zshenv.

Repository Mapping¶

How the shell concepts above map to actual files in this repo: