Environment variables - ArchWiki

Jump to content

# Environment variables

7 languages

- Deutsch
- Español
- Magyar
- 日本語
- Português
- Русский
- 中文（简体）

From ArchWiki

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 and env. To list the current environmental variables with values:

    $ 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. `~/.environment` or `~/.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] and SDDM[2] 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 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.

- `XDG_CURRENT_DESKTOP` is a freedesktop.org variable containing a colon separated list of strings that the current desktop environment identifies as [3]. Standardized values for actively developed environments are `GNOME`, `GNOME-Flashback`, `KDE`, `LXDE`, `LXQt`, `MATE`, `TDE`, `Unity`, `XFCE`, `EDE`, `Cinnamon`, `Pantheon`, and `DDE` [4].
  - 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[5].
  - `Hyprland` is informally recognized for Hyprland.

- `XDG_SESSION_DESKTOP` is similar to `XDG_CURRENT_DESKTOP`, but only permits a single string. Despite its name, it is not standardized by freedesktop.org.

- `DE` is a legacy variable indicating the desktop environment being used. There is no central documentation for what possible values are, but xdg-utils provides a reference for many desktop environments.

- `DESKTOP_SESSION` is another legacy variable, similar to `DE` but less common. It may be a path to the session's desktop entry, in `/usr/share/xsessions/` [6].

- `WINDOW_MANAGER` is 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.

- `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.

- `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.

- `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.

- `TERM` contains the type of the running terminal, e.g. `xterm-256color`. It is used by programs running in the terminal that wish to use terminal-specific capabilities.

- `MAIL` contains the location of incoming email. The traditional setting is `/var/spool/mail/$LOGNAME`.

- `ftp_proxy` and `http_proxy` contains FTP and HTTP proxy server, respectively:

    ftp_proxy="ftp://192.168.0.1:21"
    http_proxy="http://192.168.0.1:80"

- `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`

- `TZ` can be 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.

### 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).

- `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.

## See also

- Gentoo:Handbook:X86/Working/EnvVar
- Ubuntu Community Wiki - Environment Variables

Category:

- System administration