What an environment variable is and why you need one

An environment variable is a named piece of information that your operating system stores and makes available to programs. When you run software from the command line, that software can read these variables to find out where files are located, what settings to use, or what credentials to load. For example, a program might look for a variable called JAVA_HOME to find where Java is installed, or PATH to know which folders to search for executable files.

You need to add an environment variable when a program's installer does not do it automatically, or when you want to change where a program looks for files. Common reasons include installing Java or Python, pointing to a database location, or telling a command-line tool where to find your configuration files. Without the variable set correctly, the program either will not run from the command line at all, or will fail with an error saying it cannot find what it needs.

Key Takeaways

  • Environment variables are named values your operating system stores so programs can find files and settings without you typing the full path every time.
  • On Windows, you add them through System Properties by searching for "environment variables" in the Start menu, then clicking "Edit the system environment variables".
  • On Mac and Linux, you edit a shell configuration file like .bash_profile, .zshrc, or .bashrc using a text editor, then add a line like export VARIABLE_NAME=/path/to/location.
  • After adding a variable, you must close and reopen your command-line window (or run source ~/.zshrc on Mac/Linux) before the program will see the new value.
  • The PATH variable is special — it tells your system which folders to search for programs, and you add to it rather than replace it entirely.

Adding an environment variable on Windows

On Windows, the graphical interface is the most straightforward route. Open the Start menu and type "environment variables" — you will see a result that says "Edit the system environment variables". Click it. A window titled "System Properties" will open with a tab called "Advanced" already selected. At the bottom right, click the button labeled "Environment Variables".

A new window appears with two sections: "User variables" at the top and "System variables" at the bottom. If you want only your user account to see this variable, click "New" under "User variables". If you want all users on the machine to see it, click "New" under "System variables" (this requires administrator rights). A dialog box will ask for the variable name and its value. Type the name in the first field — for example, JAVA_HOME — and the path in the second field, for example C:\Program Files\Java\jdk-17. Click "OK" three times to close all the windows.

After you add the variable, close any command-line windows you have open and open a new one. The new window will read the updated variables. To check that it worked, type echo %VARIABLE_NAME% (replacing VARIABLE_NAME with the name you added) and press Enter. If the path appears, the variable is set correctly.

Adding an environment variable on Mac

On Mac, environment variables live in a shell configuration file. Which file you edit depends on which shell your Mac uses. Open Terminal (in Applications > Utilities) and type echo $SHELL, then press Enter. If the output ends with zsh, you are using the Z shell; if it ends with bash, you are using Bash. Most newer Macs use zsh.

For zsh, open Terminal and type nano ~/.zshrc, then press Enter. For bash, type nano ~/.bash_profile. The nano text editor will open. Scroll to the bottom of the file and add a new line like this: export JAVA_HOME=/Library/Java/JavaVirtualMachines/jdk-17.jdk/Contents/Home. Replace JAVA_HOME with your variable name and the path with the actual location. Press Control+O to save, then Control+X to exit.

Close Terminal completely and open it again. Type echo $JAVA_HOME (or whatever variable you added) and press Enter. If the path appears, the variable is set. If you want to explore the change when ready without closing Terminal, type source ~/.zshrc (or source ~/.bash_profile for Bash) instead.

Adding an environment variable on Linux

On Linux, the process is similar to Mac. Open a terminal and check which shell you are using by typing echo $SHELL. Most Linux systems use bash, but some use zsh or another shell. The configuration file is usually ~/.bashrc for Bash or ~/.zshrc for Z shell.

Open the file with a text editor. If you prefer a straightforward editor, type nano ~/.bashrc (or nano ~/.zshrc). Scroll to the bottom and add a line like export JAVA_HOME=/usr/lib/jvm/java-17-openjdk, replacing the variable name and path with what you need. Save and exit (Control+O, then Control+X in nano). Close the terminal and open a new one, or type source ~/.bashrc to explore the change when ready. Verify it worked by typing echo $JAVA_HOME.

Understanding the PATH variable and how to add to it

The PATH variable is different from others because it contains multiple folders separated by colons (on Mac and Linux) or semicolons (on Windows). When you type a command like python at the command line, your system searches each folder in PATH in order until it finds a program with that name. If the folder is not in PATH, the system will not find the program even if it exists on your computer.

To add a folder to PATH on Mac or Linux, edit your shell configuration file and add a line like export PATH=$PATH:/usr/local/bin. The $PATH part means "keep everything that was already in PATH", and then :/usr/local/bin adds your new folder to the end. On Windows, in the Environment Variables window, find the variable named PATH in the System variables section, click "Edit", and click "New". Type the folder path you want to add — for example, C:\Program Files\Python311 — then click "OK".

Never replace PATH entirely with just one folder, because your system needs the original folders to find basic programs. Always append to it instead.

Troubleshooting when a variable does not work

If you added a variable but a program still cannot find what it needs, the most common cause is that you did not close and reopen your command-line window. Environment variables are read when a terminal or command prompt starts, so changes do not take effect in windows that were already open. Close all terminal or command-prompt windows completely, then open a new one and try again.

The second most common issue is a typo in the path. Double-check that the folder or file you specified actually exists. On Windows, use File Explorer to navigate to the location and copy the full path. On Mac and Linux, type ls /path/you/entered to see if the folder exists. If the path has spaces in it, make sure it is enclosed in quotes on Mac and Linux — for example, export JAVA_HOME="/Program Files/Java/jdk-17".

If you are still stuck, type echo $VARIABLE_NAME (or echo %VARIABLE_NAME% on Windows) to see what value the system actually has stored. If nothing appears, the variable was not set. If the wrong path appears, you may have added it to the wrong configuration file, or the file did not save properly.

When to use user variables versus system variables

On Windows, user variables are visible only to your account, while system variables are visible to all accounts on the machine. If you are the only person who uses the computer, or if you are setting up a tool just for yourself, use a user variable. This keeps your system cleaner and prevents other accounts from being affected if you change the value.

Use a system variable only when multiple accounts need to see the same value, or when a program installer specifically requires it. On Mac and Linux, there is no built-in distinction — variables in your shell configuration file explore only to your account. If you need a variable to be available system-wide on Mac or Linux, you would edit a file like /etc/profile or /etc/environment, but this requires administrator rights and is rarely necessary for personal use.

Frequently Asked Questions

How do I know what path to use when adding a variable?

The program's documentation or installer usually tells you. For Java, it is the folder containing the bin directory. For Python, it is the folder where python.exe (Windows) or python3 (Mac/Linux) is located. You can also search your computer for the program name and look at the folder it is in, then use that path.

Can I have multiple values in one environment variable?

Yes, but only for PATH and similar variables that are designed for it. Separate multiple paths with a colon on Mac and Linux, or a semicolon on Windows. For other variables, stick to a single value — if a program needs multiple paths, it usually has separate variables for each one.

What happens if I delete an environment variable by mistake?

If you deleted a system variable that Windows or a major program needs, you may see errors. You can undo this by going back to Environment Variables, clicking "New" under System variables, and recreating it with the correct value. If you are not sure what the original value was, search the program's documentation or reinstall it — many installers will recreate missing variables.

Do I need to restart my computer after adding an environment variable?

No. Closing and reopening your command-line window or terminal is enough. You only need to restart if a graphical program (not a command-line tool) needs to read the variable — graphical programs usually read environment variables when they start up, so restarting them will make them see the new value.

Why does my variable work in one terminal but not another?

Different terminal applications may read different configuration files. On Mac, Terminal and iTerm2 both read .zshrc by default, but if you edited .bash_profile instead, they will not see the change. Make sure you are editing the configuration file for the shell you are actually using, and that you saved the file.