Environment variables and PATH

An environment variable is a name with a text value, like HOME=/home/ana. When your shell starts a program, it passes a copy of its environment along, so programs can read settings such as your home folder, your preferred editor or an API endpoint without you typing them every time.

Looking at variables

echo "$HOME"        # your home directory
echo "$USER"        # your username
echo "$SHELL"       # your login shell
env | sort          # every exported variable
printenv PATH       # one variable

Setting variables

There is a difference between a plain shell variable and an exported one. Only exported variables are passed to programs you start.

GREETING=hello            # shell variable, no spaces around =
echo "$GREETING"

export API_URL=http://localhost:8000   # visible to child programs
python3 -c 'import os; print(os.environ["API_URL"])'

DEBUG=1 npm test          # set only for this one command
unset GREETING            # remove it

Spaces matter: NAME = value is a common mistake. The shell reads that as running a command called NAME.

What PATH does

When you type python3, the shell does not search your whole disk. It looks in each folder listed in PATH, from left to right, and runs the first match.

$ echo "$PATH"
/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin

$ command -v python3
/usr/bin/python3

$ type ls
ls is /bin/ls

command -v and type show which file will actually run. When two versions of a tool are installed, the one in the folder that appears earlier in PATH wins.

Adding a folder to PATH

Tools installed per user often live in ~/.local/bin or ~/bin. To add one for the current session:

export PATH="$HOME/.local/bin:$PATH"

Putting the new folder first gives it priority; putting it last ("$PATH:$HOME/.local/bin") makes it a fallback. Always keep the existing $PATH in the value, or every normal command will suddenly be “not found”.

Making it permanent

Changes made with export disappear when you close the terminal. To keep them, add the line to your shell’s startup file:

• zsh (the default on macOS): ~/.zshrc
• bash on Linux: ~/.bashrc
• bash login shells, including bash on macOS: ~/.bash_profile, which commonly sources ~/.bashrc

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc     # reload without opening a new terminal

When you see "command not found"

Messages like bash: foo: command not found or zsh: command not found: foo mean none of the PATH folders contains foo. Check, in this order:

1. Is it spelled right, and is it actually installed?
2. Where did the installer put it? Look for its bin folder, for example with ls ~/.local/bin.
3. Is that folder in echo "$PATH"? If not, add it as shown above.
4. Did you open a new terminal or source your startup file after editing it?
5. For a script in the current folder, use ./script.sh. The current directory is deliberately not in PATH.

Keep secrets out of your history

Values typed on the command line, like export TOKEN=..., are saved in your shell history. For secrets, prefer a .env file that your tool loads and that is listed in .gitignore, or your operating system’s keychain.