To set an environment variable on a Mac, you use the export command in your shell (e.g., export MY_VAR=value) for the current session, or add that line to your shell’s startup file (like ~/.zshrc) to make it permanent. This guide covers the exact steps for both temporary and permanent variables, how to view and remove them, and common pitfalls.
What Are Environment Variables on macOS?
Environment variables are key-value pairs that store configuration settings for your shell and the programs it launches. They tell applications where to find files, how to behave, and what options to use. Common examples include PATH (which directories to search for executables), HOME (your user directory), and LANG (your locale).
On macOS, the default shell is zsh since Catalina (10.15). Earlier versions used bash. This matters because the startup files you edit differ between shells. The principles are the same, but the file names and syntax can vary slightly.
Setting a Temporary Variable (Current Session Only)
The quickest way to set a variable is with the export command in your Terminal. This affects only the current terminal window and any programs you launch from it. Once you close the window, the variable disappears.
- Open Terminal (found in /Applications/Utilities/).
- Type
export VARIABLE_NAME=valueand press Enter. For example:export API_KEY=abc123. - To verify it worked, type
echo $API_KEYand you should seeabc123.
If the value contains spaces or special characters, wrap it in quotes: export MY_VAR="hello world". Do not put spaces around the equals sign; export MY_VAR = value will fail.
Setting a Permanent Variable (Startup Files)
To make a variable persist across terminal sessions and reboots, you add the export line to your shell’s startup file. For zsh (the default), this is ~/.zshrc. For bash, it’s ~/.bash_profile or ~/.bashrc.
- Open Terminal.
- Open the file in a text editor. For example:
nano ~/.zshrc(oropen -e ~/.zshrcto use TextEdit). - Add your export line at the end of the file.
- Save and exit. In nano, press Ctrl+O, then Enter, then Ctrl+X.
- Apply the changes without restarting:
source ~/.zshrcor just open a new terminal window.
Note: ~/.zshrc is read for every interactive shell session. ~/.zprofile is read only at login. For most users, .zshrc is the right place.
Viewing and Removing Environment Variables
To see all current environment variables, type env or printenv. To see a specific one, use echo $VARIABLE_NAME (note the dollar sign).
To remove a variable for the current session, use unset VARIABLE_NAME. To remove it permanently, delete the corresponding export line from your startup file and then either restart the terminal or run source ~/.zshrc again.
Setting Variables for GUI Apps (launchctl)
Environment variables set in your shell do not automatically apply to apps launched from Finder or the Dock. For GUI applications, you need to set them via launchctl. This is a common source of confusion.
To set a variable for the current user session (available to GUI apps), use:
launchctl setenv VARIABLE_NAME value
To remove it: launchctl unsetenv VARIABLE_NAME. This only lasts until you reboot. To make it permanent, you can create a LaunchAgent plist file in ~/Library/LaunchAgents/ that runs the setenv command at login. This is more advanced and requires creating a property list file.
Common Mistakes and Troubleshooting
- Spaces around equals:
export MY_VAR = valueis wrong. Useexport MY_VAR=value. - Quoting: For values with spaces, always use quotes:
export MY_VAR="hello world". - Wrong startup file: If you’re using zsh and edit
.bash_profile, it won’t work. Check your shell withecho $SHELL. - Not sourcing: After editing the file, you must run
source ~/.zshrcor open a new terminal. Otherwise, the change isn’t active. - GUI apps not seeing variables: Remember that shell variables don’t affect Finder-launched apps. Use
launchctl setenv. - Typo in variable name: Variable names are case-sensitive.
MY_VARis different frommy_var.
PATH Variable: The Most Important One
The PATH variable is special: it’s a colon-separated list of directories where the shell looks for executable programs. If you install software that isn’t in the default PATH, you might need to add its directory.
To add a directory to PATH permanently, add this line to your ~/.zshrc:
export PATH="/your/new/directory:$PATH"
The $PATH at the end preserves the existing directories. Always include it, or you’ll break many commands. For example, to add a personal bin folder: export PATH="$HOME/bin:$PATH".
Frequently Asked Questions
How do I set an environment variable in macOS Terminal?
Use export VARIABLE_NAME=value in the terminal. This sets it for the current session only. To make it permanent, add the same line to your ~/.zshrc file (or ~/.bash_profile if you use bash).
What is the difference between .zshrc and .zprofile?
.zshrc is read every time you start an interactive shell (i.e., open a terminal window). .zprofile is read only at login, before the first shell starts. For environment variables that you want in all terminals, use .zshrc.
Why won’t my environment variable show up in apps launched from Finder?
Because Finder-launched apps don’t read your shell’s startup files. Use launchctl setenv VARIABLE_NAME value to set it for the entire user session, which GUI apps will inherit. To make it permanent, you need a LaunchAgent.
How do I unset an environment variable on a Mac?
For the current session, use unset VARIABLE_NAME. To remove it permanently, delete the export line from your startup file and then run source ~/.zshrc or restart the terminal.
Can I set an environment variable for a single command?
Yes. Prefix the command with the variable assignment: MY_VAR=value your_command. This sets the variable only for that command’s execution, not for the rest of the session.
Related
Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.
More cards in this drawer
- Infinity Essence in Sailor Piece: Farming and Uses
- Apollo.io Alternatives for Sales Prospecting
- Deploy AI Agents in a Service Desk With Human Oversight
- AIM and Yahoo Profiles: When Did You Last Look?
- Best Smartwatch Under ₹5,000 in India: What to Buy
- Chat History vs Saved Memory in AI Assistants