Environment variables

Related articles
Default applications
systemd/User#Environment variables
An environment variable is a named object that contains data used by one or more applications. In simple terms, it is a variable with a name and a value. The value of an environmental variable can for example be the location of all executable files in the file system, the default editor that should be used, or the system locale settings. Users new to Linux may often find this way of managing settings a bit unmanageable. However, environment variables provide a simple way to share configuration settings between multiple applications and processes in Linux.
Utilities
The
coreutils
package contains the programs
printenv(1)
and
env(1)
. List the current environment variable values with:
$ printenv
Note
Some environment variables are user-specific. Check by comparing the outputs of
printenv
as an unprivileged user and as root.
The
env
utility can be used to run a command under a modified environment. The following example will launch
xterm
with the environment variable
EDITOR
set to
vim
. This will not affect the global environment variable
EDITOR
.
$ env EDITOR=vim xterm
The
shell
builtin
set(1p)
allows you to change the values of shell options, set the positional parameters and to display the names and values of shell variables.
Each process stores their environment in the
/proc/$PID/environ
file. This file contains each key value pair delimited by a nul character (
\x0
). A more human readable format can be obtained with
sed
, e.g.
sed 's:\x0:\n:g' /proc/$PID/environ
.
Defining variables
To avoid needlessly polluting the environment, you should seek to restrict the scope of variables. In fact, graphical sessions and systemd services require you to set variables in certain locations for them to take effect. The scopes of environment variables are broken down into the contexts they affect:
Global
: All programs that any user runs, not including systemd services.
By user
: All programs that a particular user runs, not including user systemd services (see
systemd/User#Environment variables
) or graphical applications (see
#Graphical environment
).
Globally
Using shell initialization files
Most Linux distributions tell you to change or add environment variable definitions in
/etc/profile
or other locations. Keep in mind that there are also package-specific configuration files containing variable settings such as
/etc/locale.conf
. Be sure to maintain and manage the environment variables and pay attention to the numerous files that can contain environment variables. In principle, any shell script can be used for initializing environmental variables, but following traditional UNIX conventions, these statements should only be present in some particular files.
The following files can be used for defining global environment variables on your system, each with different limitations:
/etc/environment
is used by the
pam_env module
and is shell agnostic so scripting or glob expansion cannot be used. The file only accepts
variable=value
pairs.
/etc/profile
initializes variables for login shells
only
. It does, however, run scripts (e.g. those in
/etc/profile.d/
) and can be used by all
Bourne shell
compatible shells.
Shell specific configuration files - Global configuration files of your
shell
, initializes variables and runs scripts. For example
Bash#Configuration files
(e.g.
~/.bashrc
) or
Zsh#Startup/Shutdown files
(e.g.
~/.zshrc
).
The following Bash helper function can be used to append a number of directories to the
PATH
environment variable. Add the function at the top of the file where you define your environment (e.g.
~/.bashrc
). The function will only add directories that actually exist on the filesystem, and it will avoid creating duplicate entries.
add_paths() {
  for d in "$@"; do
    [[ -d "$d" && ! "$PATH" =~ (^|:)$d(:|$) ]] && PATH="$PATH:$d"
  done
}

add_paths ~/bin ~/scripts
Most shells (including Bash, Zsh, and
fish
) allow adding variables to the environment using the
export
command. This allows defining environment variables in a common file such as
~/my-environment.sh
:
~/my-environment.sh
export EDITOR=vim
export XDG_CACHE_HOME="$HOME/.cache"
export XDG_CONFIG_HOME="$HOME/.config"
export XDG_DATA_HOME="$HOME/.local/share"
export XDG_STATE_HOME="$HOME/.local/state"
This file can then be sourced from shell startup files:
~/.bashrc
source ~/my-environment.sh
~/.config/fish/config.fish
source ~/my-environment.sh
Using pam_env
The
PAM
module
pam_env(8)
loads the variables to be set in the environment from the following files in order:
/etc/security/pam_env.conf
and
/etc/environment
.
Note
These files are read before other files, in particular before
~/.profile
,
~/.bash_profile
and
~/.zshenv
.
The deprecated
~/.pam_environment
is not read anymore. See
FS#68945
.
/etc/environment
must consist of simple
VARIABLE
=
value
pairs on separate lines, for example:
/etc/environment
EDITOR=nano
/etc/security/pam_env.conf
has the following format:
/etc/security/pam_env.conf
VARIABLE [DEFAULT=
value
] [OVERRIDE=
value
]
@{HOME}
and
@{SHELL}
are special variables that expand to what is defined in
/etc/passwd
. The following example illustrates how to expand the
HOME
environment variable into another variable:
/etc/security/pam_env.conf
XDG_CONFIG_HOME   DEFAULT=@{HOME}/.config
Note
The variables
${HOME}
and
${SHELL}
are not linked to the
HOME
and
SHELL
environment variables, they are not set by default.
The format also allows to expand already defined variables in the values of other variables using
${
VARIABLE
}
, like this:
/etc/security/pam_env.conf
GOPATH DEFAULT=${XDG_DATA_HOME}/go
VARIABLE
=
value
pairs are also allowed, but variable expansion is not supported in those pairs. See
pam_env.conf(5)
for more information.
Per user
You do not always want to define an environment variable globally. For instance, you might want to add
/home/my_user/bin
to the
PATH
variable but do not want all other users on your system to have that in their
PATH
too. Local environment variables can be defined in many different files:
User configuration files of your
shell
, for example
Bash#Configuration files
or
Zsh#Startup/Shutdown files
.
Unless you are restricting the scope of the variables to terminals you open (e.g. command-line applications only), you are looking to modify the login shell.
systemd user environment variables
are read from
~/.config/environment.d/*.conf
.
To add a directory to the
PATH
for local usage, put following in
~/.bash_profile
:
export PATH="${PATH}:/home/my_user/bin"
To update the variable, re-login or
source
the file:
$ source ~/.bash_profile
.
Note
The dbus daemon and the user instance of systemd do not inherit any of the environment variables set in places like
~/.bashrc
etc. This means that, for example, dbus activated programs like
GNOME Files
will not use them by default. See
systemd/User#Environment variables
.
Tip
You can issue
export -p
to review the global and local environment variables declared for the user session.
Graphical environment
If an environment variable only affects graphical applications, you may want to restrict the scope of it by only setting it within the graphical session. In order of decreasing scope:
#Per Xorg session
and
#Per Wayland session
affect the whole graphical session, certainly including the DE.
#Per desktop environment session
affects the applications spawned within graphical session, potentially including the DE itself.
#Per application
affects just a particular graphical application.
Per desktop environment session
Some graphical environments, (e.g.
KDE Plasma
) support executing shell scripts at login: they can be used to set environment variables. See
KDE#Autostart
for example.
Per Xorg session
The procedure for modifying the environment of the Xorg session depends on how it is started:
Most
display managers
source
xprofile
.
startx
and
SLiM
execute
xinitrc
.
XDM
executes
~/.xsession
; see
XDM#Defining the session
.
LightDM
[1]
,
Plasma login manager
[2]
and
SDDM
[3]
additionally source startup scripts for login shells, like
~/.bash_profile
for
bash
or
~/.zprofile
and
~/.zlogin
for
zsh
.
Though the end of the script depends on which file it is, and any advanced syntax depends on the shell used, the basic usage is universal:
~/.xprofile, ~/.xinitrc, or ~/.xsession
...
export
GUI_VAR
=
value
...
Per Wayland session
Since
Wayland
does not initiate any Xorg related files,
GDM
and
KDE Plasma
source
systemd user environment variables
instead.
~/.config/environment.d/envvars.conf
GUI_VAR
=
value
No other display managers supporting Wayland sessions (e.g.
SDDM
) provide direct support for this yet. However,
LightDM
,
Plasma login manager
and
SDDM
source startup scripts for login shells on Wayland sessions too.
greetd
also sources
/etc/profile
and
~/.profile
- this behavior is controlled by its
source_profile
setting, enabled by default.
If your display manager sources startup scripts like
~/.bash_profile
and you want to use
environment.d
, you can source it like so:
~/.bash_profile
# use systemd-environment-d-generator(8) to generate environment, and export those variables
set -o allexport
source <(/usr/lib/systemd/user-environment-generators/30-systemd-environment-d-generator)
set +o allexport
Note
Other generators in
/usr/lib/systemd/user-environment-generators
like
60-flatpak
may not quote the values of environment variables. In this case the output should be sourced with
export -- "$(/usr/lib/systemd/user-environment-generators/60-flatpak)"
Per application
To set environment variables only for a specific application instead of the whole session, edit the application's
.desktop
file. See
Desktop entries#Modify environment variables
for instructions.
For
Steam
games, you can configure a program's environment by editing its launch options; see
Steam#Launch options
.
Per session or shell
Sometimes only temporary variables are required. One might wish to temporarily run executables from a specific directory without typing the absolute
PATH
each time, or use the
PATH
in a short temporary shell script.
For example, to add a session-specific directory to
PATH
, use:
$ export PATH="${PATH}:/home/my_user/tmp/usr/bin"
To add only a shell-specific directory to
PATH
, use:
$ PATH="${PATH}:/home/my_user/tmp/usr/bin"
In Bash,
PATH
is already exported by default, so both of the above will remain visible to subprocesses unless overwritten. To better illustrate the difference between exported and non-exported variables, consider the following:
$ MYVAR="shell-only"
$ bash -c 'echo $MYVAR'  # prints nothing

$ export MYVAR="session-wide"
$ bash -c 'echo $MYVAR'  # prints: session-wide
Examples
The following section lists a number of common environment variables used by a Linux system and describes their values.
Desktop environment detection
XDG_CURRENT_DESKTOP
A
freedesktop.org
variable containing a colon separated list of strings that the current
desktop environment
identifies as
[4]
. Standardized values for actively developed environments are
GNOME
,
GNOME-Flashback
,
KDE
,
LXDE
,
LXQt
,
MATE
,
TDE
,
Unity
,
XFCE
,
EDE
,
Cinnamon
,
Pantheon
, and
DDE
[5]
.
Tip
Cinnamon was registered
later
than the rest of the desktop environments. As a result, some software may still be expecting its pre-registration value
X-CINNAMON
, such as
Qt
[6]
.
Hyprland
is informally recognized for
Hyprland
.
XDG_SESSION_DESKTOP
Similar to
XDG_CURRENT_DESKTOP
, but only permits a single string. Despite its name,
it is not standardized by freedesktop.org
.
DE
A legacy variable indicating the
d
esktop
e
nvironment being used. There is no central documentation for what possible values are, but
xdg-utils
provides a reference for many desktop environments.
DESKTOP_SESSION
Another legacy variable, similar to
DE
but less common. It may be a path to the session's
desktop entry
, in
/usr/share/xsessions/
[7]
.
WINDOW_MANAGER
A variable sometimes used to
choose
the
window manager
to be used in a desktop environment, as opposed to the other variables here which are set by the already chosen display manager or desktop environment, for other programs to read.
DISPLAY
Used by the X Window System to specify the host, display and screen. The format is
hostname
:
display
.
screen
. A display refers to a collection of screens sharing a common set of input devices (keyboard, mouse, etc.). The host name was formerly used to specify the name of the machine to which the display is connected but it should be missing when the X server runs on the same computer than the X client. See
X(7)
for more details.
WAYLAND_DISPLAY
The Wayland equivalent of
DISPLAY
, set by the compositor. If unset, applications will try
wayland-0
.
XAUTHORITY
Path to the
.Xauthority
file. This file contains credentials to access the X Window Server. These are often stored under the form of a cookie (arbitrary piece of data) sent to X server to authenticate (for example,
MIT-MAGIC-COOKIE-1
).
System and session paths
HOME
Contains the path to the home directory of the current user. This variable can be used by applications to associate configuration files and such like with the user running it.
PATH
Contains a colon-separated list of directories in which your system looks for executable files. When a regular command (e.g.
ls
,
systemctl
or
pacman
) is interpreted by the shell (e.g.
bash
or
zsh
), the shell looks for an executable file with the same name as your command in the listed directories, and executes it. To run executables that are not listed in
PATH
, a relative or absolute path to the executable must be given, e.g.
./a.out
or
/bin/ls
.
Note
It is advised not to include the current working directory (
.
) into your
PATH
for security reasons, as it may trick the user to execute malicious commands.
PWD
Contains the
path to the working directory
.
OLDPWD
Contains the path to the previous working directory, that is, the value of
PWD
before last
cd
was executed.
MAIL
Contains the location of incoming email. The traditional setting is
/var/spool/mail/$LOGNAME
.
Network proxies
ftp_proxy
Contains FTP
proxy server
ftp_proxy="ftp://192.168.0.1:21"
http_proxy
Contains HTTP
proxy server
http_proxy="http://192.168.0.1:80"
Documentation paths
MANPATH
Contains a colon-separated list of directories in which
man
searches for the man pages.
Note
In
/etc/profile
, there is a comment that states "Man is much better than us at figuring this out", so this variable should generally be left unset. See
manpath(5)
.
INFODIR
Contains a colon-separated list of directories in which the
info
command searches for the info pages, e.g.,
/usr/share/info:/usr/local/share/info
Default programs
SHELL
Contains the path to the user's
preferred shell
. Note that this is not necessarily the shell that is currently running. In the event that it has no value,
Bash
will automatically set this variable to the user's login shell as defined in
/etc/passwd
or to
/bin/sh
if this cannot be determined.
PAGER
Contains command to run the program used to list the contents of files, e.g.,
/bin/less
.
EDITOR
Contains the command to run the lightweight program used for editing files, e.g.,
/usr/bin/nano
. For example, you can write an interactive switch between
gedit
under
X
or
nano
, in this example:
[ -n "$DISPLAY" ] && export EDITOR=gedit || export EDITOR=nano
VISUAL
Contains command to run the full-fledged editor that is used for more demanding tasks, such as editing mail (e.g.,
vi
,
vim
,
emacs
etc).
TERMINAL
Contains the command to run the user's preferred terminal emulator. This is not necessarily the currently running terminal (
TERM
).
BROWSER
Contains the path to the web browser. Helpful to set in an interactive shell configuration file so that it may be dynamically altered depending on the availability of a graphic environment, such as
X
:
[ -n "$DISPLAY" ] && export BROWSER=firefox || export BROWSER=links
Tip
These default programs can also be set conditionally if a
Wayland compositor
is running by using the
WAYLAND_DISPLAY
environment variable.
Miscellaneous
TERM
Contains the type of the running
term
inal, e.g.
xterm-256color
. It is used by programs running in the terminal that wish to use terminal-specific capabilities (see
terminfo(5)
). This variable should be set by the terminal emulator and overriding it from the shell is not advised.
TZ
Used to to set a time zone different to the system zone for a user. The zones listed in
/usr/share/zoneinfo/
can be used as reference, for example
TZ=":/usr/share/zoneinfo/Pacific/Fiji"
. When pointing the
TZ
variable to a
zoneinfo file
, it should start with a colon per
the GNU manual
.
Shell environment detection
See a repository about
shell environment detection
for tests to detect the shell environment. This includes login/interactive shell, Xorg session, TTY and SSH session.
See also
Gentoo:Handbook:X86/Working/EnvVar
Ubuntu Community Wiki - Environment Variables