Designing a Deterministic Zsh Startup Environment

Problem and Goal

When you invoke zsh in different contexts—login shells, interactive shells, or non‑interactive scripts—you need a predictable environment. Unintended side effects such as duplicated PATH entries, slow startup, or arbitrary code execution can break CI pipelines or make debugging hard. The goal is to define the smallest suitable design that gives you a deterministic, auditable shell across all invocation types while keeping trust boundaries clear.

Requirements

1. Environment variables that scripts must inherit (PATH, locale, etc.) must be set for every zsh, including non‑interactive ones. 2. Interactive‑only customisations (prompt, keybindings, completion, plugins) must not affect scripts. 3. Login‑only actions (e.g., setting up session‑specific variables, mounting resources) must run only for login shells. 4. The design must limit the attack surface: any file that is sourced for every zsh should be writable only by trusted users. 5. Operational checks should be available without external tooling.

Smallest Suitable Design: the Startup‑File Chain

Zsh reads a well‑defined set of files depending on how it is started. The chain is:

• /etc/zshenv and $ZDOTDIR/.zshenv – every zsh (login, interactive, non‑interactive).
• $ZDOTDIR/.zprofile and /etc/zprofile – login shells only.
• $ZDOTDIR/.zshrc and /etc/zshrc – interactive shells only.
• $ZDOTDIR/.zlogin and /etc/zlogin – login shells after .zshrc.
• $ZDOTDIR/.zlogout and /etc/zlogout – login shells on exit.

The split between .zshenv (universal) and the others (login‑ or interactive‑only) is the primary lever for separating concerns.

File‑by‑file responsibilities

• .zshenv – keep it minimal and safe for scripts: set ZDOTDIR (if needed), adjust PATH, define locale, export variables required by any command. Do not define aliases, functions, or produce output.
• .zprofile/.zlogin – login‑only tasks such as setting up environment for graphical sessions, loading ssh‑agent, or adjusting PATH for login‑specific tools.
• .zshrc – interactive customisations: prompt, keybindings, completion system, plugin managers, aliases, and functions that should never leak into scripts.

Trust and Data Boundaries

Because .zshenv runs for every zsh, a writable ZDOTDIR becomes an arbitrary‑code‑execution vector. If another user can write to the directory that holds .zshenv, they can inject commands that will execute in build systems, cron jobs, or container entrypoints. The safest practice is to ensure:

• The directory referenced by ZDOTDIR is owned by the user running the shell (or root) and is not group‑ or world‑writable.
• /etc/zshenv is root‑owned and not writable by unprivileged users.

Similarly, the fpath array that tells zsh where to look for functions must be ordered deliberately. Prepending a project‑specific directory can shadow system completions; appending it avoids accidental overrides but may make the project’s functions unavailable unless explicitly loaded.

Operational Checks

You can validate the design without extra packages:

1. Verify which directory each invocation class reads:

   zsh -c 'print -r -- $ZDOTDIR'
   zsh -l -c 'print -r -- $ZDOTDIR'
   

   The first prints the value for a non‑interactive shell; the second for a login shell. They should match the intended ZDOTDIR.
2. Trace file sourcing:

   zsh -x -i -c exit 2>&1 | grep -E 'zshenv|zprofile|zshrc|zlogin'
   

   Look for the expected sequence: zshenv, then zprofile (if login), then zshrc (if interactive), then zlogin (if login).
3. Inspect search paths:

   zsh -c 'typeset -p path fpath'
   

   Check for duplicates or unexpected entries, especially any directory that is group‑ or world‑writable.
4. Profile interactive startup (requires the built‑in zsh/zprof module):

   # near the top of .zshrc
   zmodload zsh/zprof
   # … rest of .zshrc
   # at the very end of .zshrc
   zprof
   

   Start a fresh interactive shell and read the report; functions that consume >10 ms are candidates for lazy loading.
5. Test the non‑interactive contract:

   env -i zsh -c 'command -v yourtool'
   

   If this fails because of something you placed in .zshenv, move that setting to a login‑only file.
6. Check permissions:

   ls -ld $ZDOTDIR
   for d in ${(f)$(zsh -c 'print -l $fpath')}; do ls -ld $d; done
   

   Ensure none show rw-rw-r-- or rw-rwxrwx.

Failure Modes and Mitigations

• Slow interactive startup – often caused by plugin managers that source many files in .zshrc. Mitigation: defer heavy plugins with autoload or load them on‑demand.
• Duplicated PATH/fpath entries** – can happen when a login shell sources .zshenv again via su - or sudo -i. Mitigation: use conditional checks like [[ -z $ZSHENV_LOADED ]] && export ZSHENV_LOADED=1 before modifying arrays.
• Aliases or functions from .zshenv breaking scripts** – because .zshenv runs for non‑interactive shells, any alias defined there will be expanded in scripts, potentially changing behaviour. Mitigation: keep .zshenv free of aliases and functions; if you need them, guard with [[ -o interactive ]].
• Environment drift with -f or -d** – invoking zsh with -f skips all startup files; -d skips global /etc/* files. Scripts that rely on environment set in /etc/zshenv will fail. Mitigation: document that such invocations are for testing only, or duplicate required variables in a wrapper script.

When the Design Would Change

The smallest suitable design assumes you control the startup files directly. If you adopt a framework like oh-my-zsh, prezto, or a plugin manager that rewrites .zshrc and injects code into .zshenv, the trust boundaries shift: the framework’s update mechanism becomes part of the TCB (trusted computing base). In that case you must review the framework’s security model and possibly move critical variables to a dedicated, read‑only file that the framework does not touch.

Additionally, if you run zsh in POSIX emulation mode (zsh --emulate sh or symlinked as sh), the startup‑file chain is different and the design above no longer applies. POSIX‑mode scripts should not rely on .zshenv‑only variables.

Finally, future zsh versions may adjust the exact sourcing order of shutdown files (.zlogout//etc/zlogout) or add new hooks. Always verify behaviour against the manual (man zshoptions, man zshbuiltins) shipped with your specific build.

Example Configuration

The following snippets illustrate a minimal, auditable setup that satisfies the requirements. Adjust paths to match your local conventions.

# /etc/zshenv  (read‑only, root‑owned)
# Set ZDOTDIR early; fallback to $HOME if not already exported.
export ZDOTDIR=${ZDOTDIR:-$HOME}
# Minimal, script‑safe PATH and locale.
export PATH=/usr/local/bin:/usr/bin:/bin
export LC_ALL=en_US.UTF-8

# $ZDOTDIR/.zshenv  (user‑owned, not group‑ or world‑writable)
# Only variables needed by *any* script or command.
export PATH=$HOME/bin:$PATH
# Example: set a default editor for scripts.
export EDITOR=vim

# $ZDOTDIR/.zshrc  (interactive only)
# 1. Adjust fpath – prepend personal completions, but keep system dirs after.
fpath=($HOME/.zsh/completions $fpath)
# 2. Load completion system safely; -C skips the insecure‑dir check if you trust $HOME.
autoload -Uz compinit
compinit -C
# 3. Prompt, keybindings, plugins – interactive only.
PROMPT='%F{green}%n@%m%f %F{blue}%~%f %# '
# Example: bind ^R to incremental history search.
bindkey '^R' history-incremental-search-backward
# 4. Load any plugin manager *after* the above, if you use one.
# source $HOME/.zsh/plugins/zsh-autosuggestions/autosuggestions.zsh

After editing, run the operational checks listed earlier to confirm that:

• zsh -c 'print -r -- $ZDOTDIR' returns the expected directory for non‑interactive shells.
• The trace shows zshenv → zshrc for an interactive login shell (no zprofile if you rely on .zlogin for login‑only tasks).
• typeset -p path fpath contains your personal ~/bin and ~/.zsh/completions exactly once each.
• A fresh interactive shell starts without noticeable delay; zprof shows most time spent in the prompt rendering, not in sourcing.
• env -i zsh -c 'command -v git' finds Git even when the environment is stripped, proving that .zshenv does not break non‑interactive invocations.