Gentoo Logo

Disclaimer : This handbook has been replaced by a newer version and is not maintained anymore.

[ << ] [ < ] [ Home ] [ > ] [ >> ]

5. Environment Variables


5.a. Environment Variables?

What they are

An environment variable is a named object that contains information used by one or more applications. Many users (and especially those new to Linux) find this a bit weird or unmanageable. However, this is a mistake: by using environment variables one can easily change a configuration setting for one or more applications.

Important Examples

The following table lists a number of variables used by a Linux system and describes their use. Example values are presented after the table.

Variable Description
PATH This variable contains a colon-separated list of directories in which your system looks for executable files. If you enter a name of an executable (such as ls, rc-update or emerge) but this executable is not located in a listed directory, your system will not execute it (unless you enter the full path as command, such as /bin/ls).
ROOTPATH This variable has the same function as PATH, but this one only lists the directories that should be checked when the root-user enters a command.
LDPATH This variable contains a colon-separated list of directories in which the dynamical linker searches through to find a library.
MANPATH This variable contains a colon-separated list of directories in which the man command searches for the man pages.
INFODIR This variable contains a colon-separated list of directories in which the info command searches for the info pages.
PAGER This variable contains the path to the program used to list the contents of files through (such as less or more).
EDITOR This variable contains the path to the program used to change the contents of files with (such as nano or vi).
KDEDIRS This variable contains a colon-separated list of directories which contain KDE-specific material.
CONFIG_PROTECT This variable contains a space-delimited list of directories which should be protected by Portage during updates.
CONFIG_PROTECT_MASK This variable contains a space-delimited list of directories which should not be protected by Portage during updates.

Below you will find an example definition of all these variables:

Code Listing 1.1: Example definitions

CONFIG_PROTECT="/usr/X11R6/lib/X11/xkb /opt/tomcat/conf \
                /usr/kde/3.1/share/config /usr/share/texmf/tex/generic/config/ \
                /usr/share/texmf/tex/platex/config/ /usr/share/config"

5.b. Defining Variables Globally

The /etc/env.d Directory

To centralise the definitions of these variables, Gentoo introduced the /etc/env.d directory. Inside this directory you will find a number of files, such as 00basic, 05gcc, etc. which contain the variables needed by the application mentioned in their name.

For instance, when you installed gcc, a file called 05gcc was created by the ebuild which contains the definitions of the following variables:

Code Listing 2.1: /etc/env.d/05gcc


Other distributions tell you to change or add such environment variable definitions in /etc/profile or other locations. Gentoo on the other hand makes it easy for you (and for Portage) to maintain and manage the environment variables without having to pay attention to the numerous files that can contain environment variables.

For instance, when gcc is updated, the /etc/env.d/05gcc file is updated too without requesting any user-interaction.

This not only benefits Portage, but also you, as user. Occasionally you might be asked to set a certain environment variable system-wide. As an example we take the http_proxy variable. Instead of messing about with /etc/profile, you can now just create a file (/etc/env.d/99local) and enter your definition(s) in it:

Code Listing 2.2: /etc/env.d/99local


By using the same file for all your variables, you have a quick overview on the variables you have defined yourself.

The env-update Script

Several files in /etc/env.d define the PATH variable. This is not a mistake: when you run env-update, it will append the several definitions before it updates the environment variables, thereby making it easy for packages (or users) to add their own environment variable settings without interfering with the already existing values.

The env-update script will append the values in the alphabetical order of the /etc/env.d files. The file names must begin with two decimal digits.

Code Listing 2.3: Update order used by env-update

         00basic        99kde-env       99local

The concatenation of variables does not always happen, only with the following variables: ADA_INCLUDE_PATH, ADA_OBJECTS_PATH, CLASSPATH, KDEDIRS, PATH, LDPATH, MANPATH, INFODIR, INFOPATH, ROOTPATH, CONFIG_PROTECT, CONFIG_PROTECT_MASK, PRELINK_PATH, PRELINK_PATH_MASK, PKG_CONFIG_PATH and PYTHONPATH. For all other variables the latest defined value (in alphabetical order of the files in /etc/env.d) is used.

You can add more variables into this list of concatenate-variables by adding the variable name to either COLON_SEPARATED or SPACE_SEPARATED variables (also inside an env.d file).

When you run env-update, the script will create all environment variables and place them in /etc/profile.env (which is used by /etc/profile). It will also extract the information from the LDPATH variable and use that to create /etc/ After this, it will run ldconfig to recreate the /etc/ file used by the dynamical linker.

If you want to notice the effect of env-update immediately after you run it, execute the following command to update your environment. Users who have installed Gentoo themselves will probably remember this from the installation instructions:

Code Listing 2.4: Updating the environment

# env-update && source /etc/profile

Note: The above command only updates the variables in your current terminal, new consoles, and their children. Thus, if you are working in X11, you will need to either type source /etc/profile in every new terminal you open or restart X so that all new terminals source the new variables. If you use a login manager, become root and type /etc/init.d/xdm restart. If not, you will need to logout and log back in for X to spawn children with the new variable values.

Important: You cannot use shell variables when defining other variables. This means things like FOO="$BAR" (where $BAR is another variable) are forbidden.

5.c. Defining Variables Locally

User Specific

You do not always want to define an environment variable globally. For instance, you might want to add /home/my_user/bin and the current working directory (the directory you are in) to the PATH variable but don't want all other users on your system to have that in their PATH too. If you want to define an environment variable locally, you should use ~/.bashrc or ~/.bash_profile:

Code Listing 3.1: Extending PATH for local usage in ~/.bashrc

(A colon followed by no directory is treated as the current working directory)

When you relogin, your PATH variable will be updated.

Session Specific

Sometimes even stricter definitions are requested. You might want to be able to use binaries from a temporary directory you created without using the path to the binaries themselves or editing ~/.bashrc for the short time you need it.

In this case, you can just define the PATH variable in your current session by using the export command. As long as you don't log out, the PATH variable will be using the temporary settings.

Code Listing 3.2: Defining a session-specific environment variable

# export PATH="${PATH}:/home/my_user/tmp/usr/bin"

[ << ] [ < ] [ Home ] [ > ] [ >> ]


View all

Page updated June 29, 2012

Summary: With Gentoo you can easily manage the environment variables for your system. This chapter explains how you do that, and also describes frequently used variables.

Sven Vermeulen

Grant Goodyear

Roy Marples

Daniel Robbins

Chris Houser

Jerry Alexandratos

Seemant Kulleen
Gentoo x86 Developer

Tavis Ormandy
Gentoo Alpha Developer

Jason Huebel
Gentoo AMD64 Developer

Guy Martin
Gentoo HPPA developer

Pieter Van den Abeele
Gentoo PPC developer

Joe Kallar
Gentoo SPARC developer

John P. Davis

Pierre-Henri Jondot

Eric Stockbridge

Rajiv Manglani

Jungmin Seo

Stoyan Zhekov

Jared Hudson

Colin Morey

Jorge Paulo

Carl Anderson

Jon Portnoy

Zack Gilburd

Jack Morgan

Benny Chuang


Joshua Kinard

Tobias Scherbaum

Lars Weiler

Jochen Maes

Xavier Neys

Joseph Jezak

Joshua Saddler

Gerald J. Normandin Jr.

Donnie Berkholz

Ken Nowack

Donate to support our development efforts.

Copyright 2001-2014 Gentoo Foundation, Inc. Questions, Comments? Contact us.