When Emacs loads a Lisp library, it searches for the library
in a list of directories specified by the variable load-path.
The value of this variable is a list of directories to search when
loading files with load. Each element is a string (which must be
a directory) or nil (which stands for the current working
directory).
When Emacs starts up, it sets up the value of load-path in
several steps. First, it looks for the directory containing its own
Lisp files, using default locations set when Emacs was compiled. It
saves this directory in lisp-directory. Normally, this is a
directory where the *.elc files are installed, something like
"/usr/local/share/emacs/version/lisp"
where version is the Emacs version. (In this and the following examples, replace /usr/local with the prefix appropriate for your Emacs installation.) This directory and its subdirectories contain the standard Lisp files that come with Emacs. If Emacs cannot find its own Lisp files, it will not start correctly.
If you run Emacs from the directory where it was built—that is, an
executable that has not been installed yet—Emacs instead initializes
lisp-directory using the lisp subdirectory of the
directory containing the sources from which it was built.
Emacs then initializes load-path with this lisp-directory.
If you built Emacs in a separate directory from the
sources, it also adds the lisp subdirectory of the build directory.
All of these directories are stored in the above two variables as absolute file names.
Unless you start Emacs with the --no-site-lisp option,
it then adds two more site-lisp directories to the front of
load-path. These are intended for locally installed Lisp files,
and are normally of the form:
"/usr/local/share/emacs/version/site-lisp"
and
"/usr/local/share/emacs/site-lisp"
The first one is for locally installed files for the current Emacs version; the second is for locally installed files meant for use with any installed Emacs version. (If Emacs is running uninstalled, it also adds site-lisp subdirectories from the source and build directories, if they exist. However, normally the source and build directories do not contain site-lisp subdirectories.)
If the environment variable EMACSLOADPATH is set, it modifies
the above initialization procedure. Emacs initializes
load-path based on the value of the environment variable.
The syntax of EMACSLOADPATH is the same as used for PATH;
directories are separated by ‘:’ (or ‘;’, on some
operating systems).
Here is an example of how to set EMACSLOADPATH variable (from a
sh-style shell):
export EMACSLOADPATH=/home/foo/.emacs.d/lisp:
An empty element in the value of the environment variable, whether
trailing (as in the above example, note the trailing ‘:’),
leading, or embedded, is replaced by the default value of
load-path as determined by the standard initialization
procedure. If there are no such empty elements, then
EMACSLOADPATH specifies the entire load-path. You must
include either an empty element, or the explicit path to the directory
containing the standard Lisp files, else Emacs will not function.
(Another way to modify load-path is to use the -L
command-line option when starting Emacs; see below.)
For each directory in load-path, Emacs then checks to see if
it contains a file subdirs.el, and if so, loads it. The
subdirs.el file is created when Emacs is built/installed,
and contains code that causes Emacs to add any subdirectories of those
directories to load-path. Both immediate subdirectories and
subdirectories multiple levels down are added. But it excludes
subdirectories whose names do not start with a letter or digit, and
subdirectories named RCS or CVS, and subdirectories
containing a file named .nosearch.
Next, Emacs adds any extra load directories that you specify using the -L command-line option (see Action Arguments in The GNU Emacs Manual). It also adds the directories where optional packages are installed, if any (see Packaging Basics).
It is common to add code to one’s init file (see The Init File) to
add one or more directories to load-path. For example:
(push "~/.emacs.d/lisp" load-path)
See push, for the description of push.
Dumping Emacs uses a special value of load-path. If you use
a site-load.el or site-init.el file to customize the
dumped Emacs (see Building Emacs), any changes to load-path
that these files make will be lost after dumping.
This variable holds a string naming the directory which holds Emacs’s own *.el and *.elc files. This is usually the place where those files are located in the Emacs installation tree, unless Emacs is run from its build directory in which case it points to the lisp subdirectory in the source directory from which Emacs was built.
This command finds the precise file name for library library. It
searches for the library in the same way load does, and the
argument nosuffix has the same meaning as in load: don’t
add suffixes ‘.elc’ or ‘.el’ to the specified name
library.
If the path is non-nil, that list of directories is used
instead of load-path.
When locate-library is called from a program, it returns the file
name as a string. When the user runs locate-library
interactively, the argument interactive-call is t, and this
tells locate-library to display the file name in the echo area.
This command shows a list of shadowed Emacs Lisp files. A
shadowed file is one that will not normally be loaded, despite being
in a directory on load-path, due to the existence of another
similarly-named file in a directory earlier on load-path.
For instance, suppose load-path is set to
("/opt/emacs/site-lisp" "/usr/share/emacs/29.1/lisp")
and that both these directories contain a file named foo.el.
Then (require 'foo) never loads the file in the second
directory. Such a situation might indicate a problem in the way Emacs
was installed.
When called from Lisp, this function prints a message listing the
shadowed files, instead of displaying them in a buffer. If the
optional argument stringp is non-nil, it instead returns
the shadowed files as a string.
If Emacs was compiled with support for native compilation
(see Compilation of Lisp to Native Code), then when a ‘.elc’ byte-compiled
file is found by searching load-path, Emacs will try to look
for a corresponding ‘.eln’ file holding the corresponding
natively-compiled code. The natively-compiled files are looked up in
the directories listed by the native-comp-eln-load-path.
This variable holds a list of directories where Emacs looks for
natively-compiled ‘.eln’ files. File names in the list that are
not absolute are interpreted as relative to invocation-directory
(see Operating System Environment). The last directory in the list is the
system directory, i.e. the directory with ‘.eln’ files
installed by the Emacs build and installation procedure. In each of
the directories in the list, Emacs looks for ‘.eln’ files in a
subdirectory whose name is constructed from the Emacs version and an
8-character hash that depends on the current native-compilation
ABI; the name of this subdirectory is stored in the variable
comp-native-version-dir.