oh-my-zsh plugin dependency limits when PLUGINS order varies across environments

Question

oh-my-zsh processes plugins sequentially based on their position in the PLUGINS array in .zshrc. The framework does not offer a built-in declaration system for inter-plugin dependencies, and the official documentation acknowledges ordering without guaranteeing that dependent plugins are initialized first. When the same plugin set is deployed with a different PLUGINS order or a non-standard ZSH_CUSTOM path, a plugin that expects functions or aliases from another plugin may fail to initialize, producing missing-command or syntax errors.

Because release notes and documentation do not describe a fallback strategy or dependency resolver, the supported boundary between "works locally" and "fails in production" is unclear. It is also uncertain whether newer oh-my-zsh versions introduce internal checks that alter this behavior. This question assumes a standard installation; exact behavior may vary by release, and practical verification requires comparing initialization traces across environments.

Does oh-my-zsh define any supported mechanism for declaring plugin dependencies, or is manual PLUGINS ordering the only documented approach? When a plugin references a symbol from a plugin listed later, is the resulting failure considered undefined behavior or a supported limitation? Are there version-specific guarantees about plugin initialization order that users can rely on across environments?

Tasadduq Burney · Answer

oh-my-zsh processes plugins by sequentially sourcing each entry in the PLUGINS array defined in .zshrc. The framework does not offer a built-in declaration system for inter-plugin dependencies, and the official documentation addresses ordering without guaranteeing that dependent plugins initialize first.

If a plugin expects a function, alias, or variable from another plugin positioned later in the PLUGINS array, initialization fails with a missing-command or syntax error. This failure mode is considered undefined behavior: there is no supported fallback, version-specific guarantee, or automatic dependency resolver.

Initialization order adheres to shell script sourcing semantics. Deploying the same .zshrc across environments with a different plugin arrangement—or a non-standard ZSH_CUSTOM path—can shift which symbols are available when a plugin loads, causing previously working configurations to break silently.

Verification steps (scoped to this case)

Edit the PLUGINS array in .zshrc to swap the positions of the suspected dependent and provider plugins. Restart zsh and use set -x or examine zsh -x startup output to identify which functions or aliases fail to resolve.
Execute zsh -f -c 'echo $functions[target_function]' with multiple PLUGINS orderings. If the function appears only when its provider plugin precedes the dependent one, this confirms that initialization order directly controls symbol availability.

If you can share which plugin(s) reference cross-environment symbols and the exact error message, I can suggest a concrete reordering approach.

oh-my-zsh plugin dependency limits when PLUGINS order varies across environments

1 answer

Verification steps (scoped to this case)

Your perspective belongs here.

0 question comments