Environment Variables and PATH

Understanding and modifying environment variables and PATH so your system can find installed tools

Environment variables are key-value settings that your system and apps use to find things, store preferences, and pass information around. The most important one is PATH – a list of directories your system searches when you type a command. If you install a tool and get "command not found," the fix is almost always adding its location to your PATH.

macOS uses zsh as its default shell. Environment variables are set in shell config files that run every time you open a terminal.

Viewing your current variables

See all environment variables:

env

See your current PATH (a colon-separated list of directories):

echo $PATH

Check a specific variable:

echo $HOME

Adding to PATH temporarily

This only lasts for the current terminal session:

export PATH="$PATH:/opt/my-tool/bin"

The $PATH part keeps everything already in your PATH. The new directory gets appended to the end.

Adding to PATH permanently

Edit your shell config file. For zsh (the default on macOS):

nano ~/.zshrc

Add this line at the bottom:

export PATH="$PATH:/opt/my-tool/bin"

Save (Ctrl + O, Enter, Ctrl + X to exit nano), then reload the config:

source ~/.zshrc

To verify it worked:

echo $PATH

If you're using bash instead of zsh, edit ~/.bash_profile or ~/.bashrc instead.

Setting other environment variables

Add these to ~/.zshrc the same way:

export EDITOR="code"
export JAVA_HOME="/Library/Java/JavaVirtualMachines/jdk-21.jdk/Contents/Home"

Common variables

HOME – your home directory (/Users/yourname)
USER – your username
PATH – directories searched for commands
EDITOR – your preferred text editor
SHELL – your current shell (/bin/zsh)
JAVA_HOME – where Java is installed (required by many Java tools)
NODE_PATH – additional directories for Node.js modules

Troubleshooting "command not found"

Find where the tool was installed: which tool-name or where tool-name
If it returns nothing, check common install locations: /usr/local/bin, /opt/homebrew/bin, ~/.local/bin
Add the directory containing the tool to your PATH in ~/.zshrc
Run source ~/.zshrc to reload
Try the command again

If you installed something with Homebrew and it's not found, Homebrew may have printed instructions to add it to your PATH during installation. Run brew doctor to check for issues.

Frequently Asked Questions

What happens if I mess up my PATH?▾

Your terminal won't find basic commands like ls or git. Don't panic – just open a new terminal and fix your shell config file. You can always use the full path to an editor (like /usr/bin/nano ~/.zshrc) even if PATH is broken. On Windows, use the System Properties GUI to fix it.

What's the difference between user and system environment variables?▾

User variables only affect your account. System variables apply to every user on the computer. On Mac/Linux, ~/.zshrc or ~/.bashrc are user-level, while /etc/environment or /etc/profile are system-level. On Windows, the Environment Variables dialog shows both sections separately.

Do I need to restart my computer after changing PATH?▾

No. On Mac/Linux, run source ~/.zshrc (or source ~/.bashrc) to reload immediately, or just open a new terminal window. On Windows, open a new terminal window – existing windows keep the old values. No reboot required.

Should I prepend or append to PATH?▾

It matters. Directories listed first in PATH take priority. If you want your custom tool to override a system version, prepend it (export PATH="/my/path:$PATH"). If you want system defaults to take priority, append it (export PATH="$PATH:/my/path"). Appending is safer if you're not sure.

Can environment variables contain spaces?▾

Yes, but you need to quote the value. Use export MY_VAR="some value with spaces" on Mac/Linux, or set the value with quotes in the Environment Variables dialog on Windows. In PowerShell, $env:MY_VAR = "some value with spaces" works fine.