.zshrc and .zprofile · Command Line Guide · 2024

Source: .zshrc and .zprofile · Command Line Guide · 2024

Comparing .zshrc or .zprofile zsh configuration files. How to set PATH and aliases. Configuring macOS Zsh shell.

Here’s a close look at differences among zsh configuration files. Zsh shell offers four configuration files with no discernible differences. Particularly, ~/.zshrc and ~/.zprofile appear to be identical. Here you’ll learn the difference and discover a simple guideline for shell configuration.

You can read more about Shell Configuration and setting the Mac PATH.

Before you get started

You’ll need a terminal application to configure the shell. Apple includes the Mac terminal but I prefer Warp Terminal. Warp is an easy-to-use terminal application, with AI assistance to help you learn and remember terminal commands. Download Warp Terminal now; it’s FREE and worth a try.

Why configure the shell

You’ll need to configure the shell when setting up a development environment. You may want aliases for hard-to-remember commands and a custom prompt that can display the directory you’re in, among other things. More important are critical environment variables that make programs available or alter shell behavior. The EDITOR environment variable, for example, sets your preferred text editor. And often you must set the PATH environment variable when installing a programming language or software utilities.

Zsh configuration files

Zsh configuration files are kept in the user’s home directory and are named with a dot as the first character to keep them hidden by default. Zsh recognizes four different configuration files in the user’s home directory: ~/.zshenv, ~/.zprofile, ~/.zshrc, and ~/.zlogin. Differences among these files are not obvious, especially between zprofile and zshrc files. Here you’ll learn how to use each of these files.

Interactive vs. non-interactive and login vs. non-login

Shell sessions can be classified as interactive or non-interactive, login or non-login.

On macOS, each new terminal session is treated as a login shell, so opening any terminal window starts an interactive login session. Also, a system administrator who connects to a remote server via SSH initiates an interactive login session.
If a terminal window is already open and you run the command zsh to start a subshell, it will be interactive and non-login. Beginners seldom use subshells.
Automated shell scripts run without login or any user prompting. These are non-interactive and non-login.
Few people ever encounter a non-interactive login shell session. It requires starting a script with a special flag or piping output of a command into an ssh connection.

How Zsh configuration files get sourced

Different kinds of shell sessions necessitate different shell configurations. Here’s how the configuration files are loaded and applied (“sourced”):

~/.zshenv – This is loaded universally for all types of shell sessions (interactive or non-interactive, login or non-login). It is the only configuration file that gets loaded for non-interactive and non-login scripts like cron jobs. However, macOS overrides this for PATH settings for interactive shells.
~/.zprofile – Loaded for login shells (both interactive and the rare non-interactive sessions). MacOS uses this to set up the shell for any new terminal window. Subshells started from within the terminal window inherit settings but don’t load ~/.zprofile again.
~/.zshrc – Loaded only for interactive shell sessions. It is loaded whenever you open a new terminal window or launch a subshell from a terminal window.
~/.zlogin – Only used for login shell configurations, loaded after .zprofile. Loaded whenever you open a new terminal window.

Best uses for each configuration file

Here’s how you can use each configuration file:

~/.zshenv – It is universally loaded, so you could use it to configure the shell for automated processes like cron jobs. However, it is best to explicitly set up environmental variables for automated processes in scripts and leave nothing to chance. As a beginner, you will not use this configuration file; in fact, few experienced macOS developers use it.
~/.zprofile – Homebrew recommends setting the PATH variable here. There’s a reason PATH should be set in ~/.zprofile and not the universal ~/.zshenvfile: The macOS runs a utility path_helper (from /etc/zprofile) that sets the PATH order before ~/.zprofile is loaded.
~/.zshrc – This is the configuration file that most developers use. Use it to set aliases and a custom prompt for the terminal window. You can also use it to set the PATH (which many people do) but ~/.zprofile is preferred.
~/.zlogin – Seldom used. Only important in managing the order of initialization tasks for login shells in complex environments. It can be used to display messages or system data.

Guidelines for use of `~/.zprofile` and `~/.zshrc`

Here’s the current recommended practice:

Use ~/.zprofile to set the PATH and EDITOR environment variables.
Use ~/.zshrc for aliases and a custom prompt, tweaking the appearance and behavior of the terminal.
If you write automated shell scripts, check and set environment variables in the script.

The ~/.zprofile file was originally intended for time-consuming tasks at login that should not be repeated whenever a new shell was initiated. MacOS now launches any new terminal window as a login shell, loading both ~/.zprofile and ~/.zshrc files without concern for the shell startup time.

The key advantage of the ~/.zprofile file (versus ~/.zshenv) is that it sets environment variables such as PATH without override from macOS. The ~/.zshrc file could be used for the same but, by convention and design, is intended for customizing the look and feel of the interactive terminal.

What’s next

For instructions to configure the shell, see Shell Configuration and setting the Mac PATH.

My mac.install.guide is a trusted source of installation guides for professional developers. Take a look at the Mac Install Guide home page for tips and trends and see what to install next.