When Emacs loads a Lisp library, it searches for the library
in a list of directories specified by the variable
The value of
load-path is initialized from the environment
EMACSLOADPATH, if that exists; otherwise its default
value is specified in emacs/src/epaths.h when Emacs is built.
Then the list is expanded by adding subdirectories of the directories
in the list.
The syntax of
EMACSLOADPATH is the same as used for
‘:’ (or ‘;’, according to the operating system) separates
directory names, and ‘.’ is used for the current default directory.
Here is an example of how to set your
EMACSLOADPATH variable from
csh .login file:
setenv EMACSLOADPATH .:/user/bil/emacs:/usr/local/share/emacs/20.3/lisp
Here is how to set it using
export EMACSLOADPATH EMACSLOADPATH=.:/user/bil/emacs:/usr/local/share/emacs/20.3/lisp
Here is an example of code you can place in your init file (see Init File) to add several directories to the front of your default
(setq load-path (append (list nil "/user/bil/emacs" "/usr/local/lisplib" "~/emacs") load-path))
In this example, the path searches the current working directory first, followed then by the /user/bil/emacs directory, the /usr/local/lisplib directory, and the ~/emacs directory, which are then followed by the standard directories for Lisp code.
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.
Therefore, if you want to change
load-path temporarily for
loading a few libraries in site-init.el or site-load.el,
you should bind
load-path locally with
let around the
The default value of
load-path, when running an Emacs which has
been installed on the system, includes two special directories (and
their subdirectories as well):
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.
There are several reasons why a Lisp package that works well in one Emacs version can cause trouble in another. Sometimes packages need updating for incompatible changes in Emacs; sometimes they depend on undocumented internal Emacs data that can change without notice; sometimes a newer Emacs version incorporates a version of the package, and should be used only with that version.
Emacs finds these directories' subdirectories and adds them to
load-path when it starts up. Both immediate subdirectories and
subdirectories multiple levels down are added to
Not all subdirectories are included, though. Subdirectories whose names do not start with a letter or digit are excluded. Subdirectories named RCS or CVS are excluded. Also, a subdirectory which contains a file named .nosearch is excluded. You can use these methods to prevent certain subdirectories of the site-lisp directories from being searched.
If you run Emacs from the directory where it was built—that is, an
executable that has not been formally installed—then
normally contains two additional directories. These are the
site-lisp subdirectories of the main build directory. (Both
are represented as absolute file names.)
This command finds the precise file name for library library. It searches for the library in the same way
loaddoes, 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
locate-libraryis called from a program, it returns the file name as a string. When the user runs
locate-libraryinteractively, the argument interactive-call is
t, and this tells
locate-libraryto 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
For instance, suppose
load-pathis 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
nil, it instead returns the shadowed files as a string.