← Full reference

Environment variables: env, export, printenv

A process's environment — export, env -i and env VAR=…, printenv, where to set variables and which files bash reads

The environment is a set of NAME=value pairs every process receives from its parent at startup. It's how settings are passed to programs: PATH, HOME, LANG, EDITOR, database addresses. A shell variable gets into the environment of child processes only if it has been exported (export). env runs a command with a modified environment, printenv prints it. Important: a child process gets a copy of the environment — it can't change its parent's environment.

Syntax

export NAME=value              # a shell variable + into the children's environment
NAME=value command             # a variable for one command only
env [-i] [-u NAME] [NAME=value…] [command [arguments…]]
printenv [NAME…]

bash builtins

CommandWhat it does
export NAME=valueset and export
export NAMEexport an already existing variable
export -n NAMEremove from the environment, keeping it as a shell variable
export -plist exported variables as declare -x …
declare -x NAME=valuesame as export
unset NAMEdelete the variable completely
NAME=value commandset only in this command's environment
set -aexport every variable set from this point on

env options

OptionWhat it does
no argumentsprint the environment (like printenv)
NAME=value … commandrun the command with added or changed variables
-i, -start with an empty environment
-u NAMEremove a variable from the command's environment
-C directorychange to the directory before running the command
-S 'string'split the string into arguments — for a shebang: #!/usr/bin/env -S python3 -u
-0when printing, separate variables with a NUL byte
-vshow what env does at each step

env exit codes: 125 — an error in env itself, 126 — the command was found but can't be run, 127 — the command wasn't found, otherwise — the command's own code.

printenv

FormWhat it does
printenvthe whole environment, one NAME=value per line
printenv HOME PATHonly the values of the given variables, one per line
exit code1 if at least one of the variables is missing

printenv sees only exported variables — a handy way to check that a variable will really reach programs.

Common variables

VariableWhat it holds
PATH:-separated directories where commands are looked up
HOME / USER / SHELLhome directory / user name / login shell
PWD / OLDPWDcurrent / previous directory
LANG, LC_*, LC_ALLlocale: language, encoding, number and date formats; LC_ALL overrides the rest
TZtime zone: TZ=Europe/Berlin date
EDITOR / VISUAL / PAGERdefault editor and pager for crontab -e, git, man
TERMterminal type
DEBIAN_FRONTEND=noninteractiveapt asks no questions
http_proxy / https_proxy / no_proxyproxy for curl, wget, apt

Where to set variables permanently

FileWho reads itWhat for
/etc/environmentPAM at login (login, ssh, su, cron) — not bashsystem-wide variables; format NAME=value, no export and no $VAR substitution
/etc/profile and /etc/profile.d/*.shbash and sh login shellssystem-wide login settings; add your own as a separate file in profile.d
~/.profile (or ~/.bash_profile)a specific user's bash login shellpersonal variables, PATH; on Ubuntu ~/.profile sources ~/.bashrc
/etc/bash.bashrc, ~/.bashrcan interactive non-login bash (a new terminal window, bash inside a session)aliases, prompt, functions
$BASH_ENVnon-interactive bash (scripts)a file that runs before the script

Which files are read:

How bash was startedWhat it reads
ssh login, su -, bash -l (login)/etc/profile → /etc/profile.d/*.sh → the first of ~/.bash_profile, ~/.bash_login, ~/.profile
a new terminal window, bash (interactive)/etc/bash.bashrc → ~/.bashrc
a script, bash -c '…', cronnothing except the file from $BASH_ENV; the environment is only what the parent passed

To check whether the current shell is a login shell: shopt -q login_shell && echo login.

Examples

# a variable for one command only
LANG=C sort file.txt
TZ=UTC date

# a shell variable isn't visible to children until it's exported
APP_MODE=dev
bash -c 'echo "[$APP_MODE]"'      # []
export APP_MODE
bash -c 'echo "[$APP_MODE]"'      # [dev]

# run a program in a clean environment — the way cron or systemd will see it
env -i PATH=/usr/bin:/bin bash -c 'env'

# remove one variable for a command
env -u http_proxy curl -s http://localhost/

# check one variable; exit code 1 if it's missing
printenv HOME
printenv NO_SUCH_VAR || echo "not set"

# find variables by name
env | grep -i proxy

# load variables from a .env file into the environment
printf 'DB_HOST=localhost\nDB_PORT=5432\n' > /tmp/app.env
set -a; source /tmp/app.env; set +a
printenv DB_HOST

# add a directory to PATH permanently for all login shells
echo 'export PATH="$PATH:/opt/tools/bin"' > /etc/profile.d/tools.sh

# a portable shebang: find the interpreter via PATH
#!/usr/bin/env python3

Pitfalls

  • A script can't change the environment of the shell that called it. ./set-vars.sh with export X=1 inside won't set X in your terminal. You need to run the file in the current shell: source set-vars.sh.
  • Without export a variable doesn't reach programs. X=1 followed by python3 app.py — the program won't see X. Check with printenv X.
  • ~/.bashrc isn't read by scripts or cron. And on Ubuntu it starts with a "not an interactive shell — exit" check, so even bash -c won't pick it up. Set variables for scripts in the script itself or in the crontab.
  • Lines in /etc/profile.d/ don't take effect until a new login. Sessions that are already open won't see them: log in again or run source /etc/profile.d/file.sh.
  • /etc/environment is not a script. export, $PATH and commands don't work there: PAM reads the file, not bash. The value PATH="$PATH:/x" is stored literally.
  • sudo resets the environment. By default (env_reset) a command under sudo gets an almost empty environment and its own PATH. To pass a variable: sudo VAR=value command or sudo -E.
  • env VAR=$X command substitutes $X in your shell, before env starts. To have the child process do the substitution, put the command in single quotes: env X=1 bash -c 'echo $X'.

See also

variables · set · sudo · cron · su · which