The Comfort Zone: `.zshrc`
For most of us who learned on the fly, the `.zshrc` file is command-central. It's the first place we learn to customize our shell. We throw in our aliases, tweak our prompt, set up some functions, and maybe configure our command history. It’s the trusty
file that gets sourced every time we open a new terminal window, making our interactive life easier. And for 90% of day-to-day tasks, this works perfectly. The problem is, this convenience creates a powerful habit: when something needs to be configured in the shell, we instinctively put it in `.zshrc`. This includes one of the most critical pieces of configuration: environment variables.
The Hidden Detail: The Startup File Symphony
Here's the detail that trips people up: `.zshrc` is not the only startup file, and it’s not always the right one. Zsh, like other shells, has a whole sequence of configuration files it reads from, and the order matters immensely. There are files for login shells, interactive shells, and—this is the crucial part—all shell invocations. Most self-taught developers lump everything into `.zshrc` because it handles interactive sessions, which is what they see. But the shell is constantly running in the background for non-interactive tasks, like scripts executed by a build tool, a cron job, or even a GUI application that needs to find a command-line utility. These non-interactive shells often don't read `.zshrc` at all.
Meet `.zshenv`: The File You Should Be Using
The real workhorse for environment variables should be a different file: `.zshenv`. According to official Zsh documentation and seasoned developers, `.zshenv` is designed for one primary purpose: setting environment variables. Its superpower is that it is always sourced, for every single type of shell session—login, interactive, or non-interactive—unless explicitly disabled. When you declare `export PATH="$HOME/.local/bin:$PATH"` or `export EDITOR='nvim'` in `.zshenv`, you guarantee that every program launched from your user account, whether from a terminal or a script, will know about it. Placing these in `.zshrc` means they only exist in the context of an interactive terminal, creating a frustrating inconsistency.
When `.zshrc` Goes Wrong
Let’s make this concrete. Say you install a new programming language and add its binary path to `PATH` inside your `.zshrc` file. In your terminal, everything works. But then, you open your code editor, which uses a linter that relies on that new language. The editor, not being an interactive shell, doesn't source `.zshrc`. It can't find the binary, and you're left with mysterious "command not found" errors inside your IDE. You might spend hours debugging your editor's configuration, when the root cause is that the environment variable was defined in the wrong place. The solution is simple: move environment variable exports from `.zshrc` to `.zshenv`. Keep `.zshrc` for things that only matter when you're actively typing in a terminal, like aliases, functions, and prompt settings.
A Quick Guide to the Zsh Orchestra
To complete the picture, it's helpful to know the main players in the Zsh startup order. Think of it like this: 1. `.zshenv`: The universal file. Sourced first and for all shells. Use it for environment variables like `PATH`, `EDITOR`, etc. 2. `.zprofile`: Sourced for login shells (e.g., when you first log in via SSH or, on some systems like macOS, every new terminal). It runs after `.zshenv` but before `.zshrc`. 3. `.zshrc`: Sourced for interactive shells. This is for your aliases, functions, and prompt. 4. `.zlogin`: Also for login shells, but sourced after `.zshrc`. It's less common, but useful for running commands once the entire shell environment is configured. By respecting this hierarchy, you ensure your shell environment is consistent, predictable, and bug-free, no matter how it's being used.
