Library Search - GNU Emacs Lisp Reference Manual

When Emacs loads a Lisp library, it searches for the library in a list of directories specified by the variable load-path.

— 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 name) or nil (which stands for the current working directory).

Each time Emacs starts up, it sets up the value of load-path in several steps. First, it initializes load-path to the directories specified by the environment variable EMACSLOADPATH, if that exists. The syntax of EMACSLOADPATH is the same as used for PATH; directory names are separated by ‘:’ (or ‘;’, on some operating systems), and ‘.’ stands for the current default directory. Here is an example of how to set EMACSLOADPATH variable from sh:

If EMACSLOADPATH is not set (which is usually the case), Emacs initializes load-path with the following two directories:

The first one is for locally installed packages for a particular Emacs version; the second is for locally installed packages meant for use with all installed Emacs versions.

If you run Emacs from the directory where it was built—that is, an executable that has not been formally installed—Emacs puts two more directories in load-path. These are the lisp and site-lisp subdirectories of the main build directory. (Both are represented as absolute file names.)

Next, Emacs “expands” the initial list of directories in load-path by adding the subdirectories of those directories. 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 directory that you specify using the ‘-L’ command-line option (see Action Arguments). 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 Init File) to add one or more directories to load-path. For example:

Dumping Emacs uses a special value of load-path. If the value of load-path at the end of dumping is unchanged (that is, still the same special value), the dumped Emacs switches to the ordinary load-path value when it starts up, as described above. But if load-path has any other value at the end of dumping, that value is used for execution of the dumped Emacs also.

— Command: locate-library library &optional nosuffix path interactive-call

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.

— Command: list-load-path-shadows &optional stringp

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/23.3/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.

15.3 Library Search