Choosing Between Autoloading Zsh Functions and Sourcing Scripts in .zshrc

Decision Overview

When configuring an interactive zsh session, you can either source helper scripts directly in .zshrc or let zsh autoload user‑defined functions from $fpath. The goal is a fast startup, reproducible configuration across hosts, and early detection of syntax errors.

Option Comparison

Option	How it Works	Startup Impact	Error Detection
Autoload with $fpath	Function name is declared; when first invoked, zsh searches $fpath for a file named after the function and loads it.	Minimal during .zshrc parsing; memory is used only on first call.	Syntax errors surface at first invocation, not at shell start.
Source script (. file)	The script is executed immediately while .zshrc is read, defining functions and running side effects.	Linear with the number of sourced files; each adds to startup time.	Errors are caught during .zshrc execution, causing immediate failure.

Trade‑offs

• Startup Speed: Autoload keeps .zshrc lean and defers loading until needed, which is valuable when you have many helper scripts. Sourcing can noticeably slow the shell, especially on slower disks or with many files.
• Early Failure: Sourcing fails fast; any syntax error stops the shell from starting. Autoload hides errors until the function is called, which may be later in the session.
• Portability: Autoload relies on $fpath order. If a system path shadows a user file, the function may not load. Sourcing guarantees the function is defined before any later commands.
• Side Effects: Functions that must run during shell initialization (e.g., prompt setup) cannot be autoloaded; they need to be sourced or defined inline.
• Alias Expansion: Without -U, autoload expands active aliases at load time, which can alter the function body unexpectedly.
• Compiled Files: Stale .zwc files can shadow edited sources. Delete or regenerate them after changes.

Concrete Implementation

1. Create a directory for user functions:

mkdir -p ~/.zsh/functions

2. Add the directory to $fpath early in .zshrc:

fpath+=($HOME/.zsh/functions)

3. Define a function in a separate file. For example, ~/.zsh/functions/myecho:

myecho() {
  printf '%s\n' "$*"
}

4. Mark the function for lazy loading:

autoload -Uz myecho

5. Verify lazy loading. After launching zsh, run:

type myecho
# Expected: myecho is a function
myecho hello
# Expected output: hello

Validation Test

Run a single‑shot test that mimics the startup process:

zsh -f -c '
  fpath+=("$HOME/.zsh/functions")
  autoload -Uz myecho
  type myecho
  myecho ok
'

Check that the function is defined only when invoked and that the output is correct.

Measuring Startup Impact

Before and after moving helper scripts from source to autoload, compare interactive startup times:

# Baseline with source
zsh -i -c exit > /dev/null
# After change
zsh -i -c exit > /dev/null

Use time to capture the elapsed time. A noticeable reduction indicates successful optimization.

Practical Checklist

• Place user directories before system paths in $fpath to ensure precedence.
• Use -U with autoload unless you deliberately want alias expansion.
• Regenerate .zwc files after editing functions or clear them with rm ~/.zsh/functions/*.zwc.
• Do not autoload functions required before the first prompt (e.g., prompt themes).