Where apps hide your files

Finding, creating and editing .zshrc

Updated 2026-10-28 · 6 min read

Your zsh settings file is .zshrc in your home folder. It is hidden, and on a fresh Mac it often does not exist until you make it, so here is how to check, create it and apply changes safely.

The location

~/.zshrc

That is /Users/<your-name>/.zshrc, directly in your home folder, not in Documents or Library. Apple says zsh has been the default shell for new user accounts since macOS Catalina (10.15). An account first set up on an older macOS may still use bash, so check:

echo $SHELL

A reply of /bin/zsh means .zshrc is the file for you. To see whether yours exists:

ls -la ~/.zshrc

"No such file or directory" is normal on a new account. macOS does not create the file for you, although some installers add one when they set themselves up.

Create it, or back it up first

If it does not exist yet, create an empty one:

touch ~/.zshrc

touch does nothing to an existing file except update its modified time, so it is safe either way. If the file already exists, make a copy before you change anything, so a mistake is one command away from undone:

cp ~/.zshrc ~/.zshrc.backup

Edit it

In TextEdit:

open -e ~/.zshrc

Before you type anything with quotes, turn off Edit > Substitutions > Smart Quotes in TextEdit. Curly quotes look fine but break shell commands. If the window shows a formatting ruler, choose Format > Make Plain Text.

In Terminal, nano ~/.zshrc opens the file in a simple editor. On recent macOS, nano is a link to the similar pico editor, and the keys are the same: ⌃O then Return saves, ⌃X exits.

To see the file in Finder, open your home folder and press ⇧⌘. (Shift-Command-Period) to show hidden files. Press it again to hide them.

Check and apply your changes

Before loading the file, you can ask zsh to check its syntax without running anything:

zsh -n ~/.zshrc

No output means no syntax errors. To apply the file to the tab you are in:

source ~/.zshrc

The cleanest test is a new Terminal tab or window, which reads the file fresh. Keep your current tab open until the new one starts properly, so you have a working shell to fix things from. An error on startup names the line, for example /Users/<your-name>/.zshrc:12: command not found, which makes a typo easy to find. Re-sourcing an edited file in the same tab can add a PATH entry twice; a new tab avoids that.

.zshrc, .zprofile and the others

The zsh manual lists the startup files in this order:

File	When it runs
/etc/zshenv, then ~/.zshenv	Every zsh, including scripts. Keep it tiny.
/etc/zprofile, then ~/.zprofile	Login shells.
/etc/zshrc, then ~/.zshrc	Interactive shells: your prompt, aliases, completion.
/etc/zlogin, then ~/.zlogin	Login shells, after .zshrc. Rarely used.

Terminal opens each new window and tab with a login shell by default, so both .zprofile and .zshrc run there. The split matters elsewhere: an editor's built-in terminal, an SSH session or a script may run only some of them.

A rule of thumb that holds up: put aliases, prompt settings and completion setup in .zshrc. Put PATH changes and tool setup that other programs need in .zprofile. Homebrew's installer suggests adding its shellenv line to .zprofile; on Apple silicon that line points to /opt/homebrew, while an Intel install uses /usr/local.

On the Mac used for this guide, /etc/zshrc and /etc/zprofile exist and /etc/zshenv does not. The /etc files are Apple's: leave them alone, because macOS updates can replace them. /etc/zshrc also sets your history file to ~/.zsh_history, and Terminal's add-on script keeps per-tab history in ~/.zsh_sessions. Both are private, so do not paste them into a bug report.

What people usually put in it

• Aliases, such as a short name for a long command.
• export lines for variables like EDITOR.
• A PATH addition for your own scripts, for example export PATH="$HOME/bin:$PATH".
• Prompt settings, setopt lines and completion setup.

Keep it short and add a comment above each block. When a new Terminal window starts slowly, the usual cause is something heavy in this file, such as a tool that loads on every start.

Using a different location

zsh looks for these files in $ZDOTDIR if that variable is set, and in your home folder otherwise. If you keep dotfiles in ~/.config/zsh, for example, set ZDOTDIR in ~/.zshenv: that file is read from your home folder before ZDOTDIR takes effect, and the rest then come from the new folder. Without that, a .zshrc stored anywhere else is silently ignored.

When changes seem to do nothing

• You edited the wrong file: .bashrc and .bash_profile are for bash, not zsh.
• Your account's shell is bash. echo $SHELL shows the login shell. Apple documents two ways to switch: chsh -s /bin/zsh in Terminal, or in System Settings > Users & Groups, Control-click your name and choose Advanced Options.
• The file has curly quotes or other characters from a word processor. Use plain text only.
• Another file later in the order, or a framework such as Oh My Zsh, overrides your setting. Add echo "zshrc loaded" at the top temporarily to confirm the file runs, then remove it.

Backups and moving to a new Mac

.zshrc is a small text file, so copy it to the new Mac's home folder. Check it before you do. Paths inside it, such as /Users/<old-name>/ or /usr/local/bin, may not exist on the new machine, and an Intel Homebrew path will not work on Apple silicon. Do not put API keys, tokens or passwords in it, especially if you keep your dotfiles in a Git repository.

Why a normal search misses it

A file starting with a dot is hidden, so Spotlight and Finder searches leave it out, and .zshrc has no extension for a search to match.

Finding it again

Type zshrc into Everywhere and the home folder copy appears along with any backups such as .zshrc.backup, .zshrc.pre-oh-my-zsh or a copy in a dotfiles repo. Press ⌘T to open a Terminal in that folder. It matches names only, so it cannot tell you which of them contains a given alias.

Common questions

Where is .zshrc on a Mac?

At ~/.zshrc, directly in your home folder. It is hidden, so press ⇧⌘. in a Finder window or run ls -la ~/.zshrc in Terminal.

Why is there no .zshrc on my Mac?

macOS does not create one by default. Run touch ~/.zshrc to make an empty file, then open -e ~/.zshrc or nano ~/.zshrc to edit it.

Should I put settings in .zshrc or .zprofile?

Aliases, prompt and completion go in .zshrc. PATH changes and tool setup that other programs need usually go in .zprofile, which login shells read.

How do I reload .zshrc without restarting Terminal?

Run source ~/.zshrc in the tab, or open a new tab, which reads the file fresh. zsh -n ~/.zshrc checks the file for syntax errors first.