‘load-path’ lists all the directories where Emacs should look for Elisp files. The first file found is used, therefore the order of the directories is relevant.
Preference is given to byte-compiled files (
*.elc) when both a byte-compiled file and a source file (
*.el) are found. Therefore, make sure to recompile files after making changes to them (or don’t compile the files at all).
To add a single directory to the front of your
(add-to-list 'load-path "~/.emacs.d/lisp/")
Adding a directory to the variable
‘load-path’ does not also add its subdirectories. The current directory is the directory containing the currently visited file, or if the current buffer does not visit a file the directory from which Emacs was started. To add a directory to the
‘load-path’ the current directory has to be temporarily changed by binding
‘default-directory’. To recursively add the sub-directories of the current directory to the end of the
‘load-path’ do this:
(let ((default-directory "~/.emacs.d/lisp/")) (normal-top-level-add-subdirs-to-load-path))
This avoids subdirectories not starting with letters or digits, those named
CVS, and those containing a file named
To add only some subdirectories, pass the list as a second argument. For example:
(let ((default-directory "~/.emacs.d/lisp/")) (normal-top-level-add-to-load-path '("emms" "erc" "planner" "w3")))
To have libraries in particular paths take precedence over other libraries elsewhere with the same name, put those paths at the beginning of
(let ((default-directory "~/.emacs.d/lisp/")) (setq load-path (append (let ((load-path (copy-sequence load-path))) ;; Shadow (normal-top-level-add-subdirs-to-load-path)) load-path)))
Assuming that you install packages in
~/.emacs.d/lisp/ and that some of the installed packages are single libraries while others are placed inside their own sub-directories you need to combine the steps from above.
(let ((default-directory "~/.emacs.d/lisp/")) (normal-top-level-add-to-load-path '(".")) (normal-top-level-add-subdirs-to-load-path))
Since various packages store information in
~/.emacs.d/, it is unwise to add all of its sub-directories to
‘load-path’. Above we only added the sub-directory
lisp to avoid loading files that aren’t libraries.
To install all directories to the beginning of the
(let ((default-directory "~/.emacs.d/lisp/")) (setq load-path (append (let ((load-path (copy-sequence load-path))) ;; Shadow (append (copy-sequence (normal-top-level-add-to-load-path '("."))) (normal-top-level-add-subdirs-to-load-path))) load-path)))
If you are using Emacs 23 you can use
‘user-emacs-directory’ to construct a path to one of its sub-directories.
(concat user-emacs-directory (convert-standard-filename "lisp/"))
Note how we use
‘convert-standard-file-name’ to construct a path which is valid on all supported platforms.
If you use an older versions of Emacs you can backport this useful variable.
(unless (boundp 'user-emacs-directory) (defvar user-emacs-directory "~/.emacs.d/" "Directory beneath which additional per-user Emacs-specific files are placed. Various programs in Emacs store information in this directory. Note that this should end with a directory separator. See also `locate-user-emacs-file'."))
The default value of
‘load-path’ includes two special directories recursively:
/usr/local/share/emacs/site-lisp. (On Windows, the equivalent location is
C:\Program Files\emacs-VERSION\site-lisp.) The first directory contains packages for a particular Emacs version; the second contains packages for all installed versions of Emacs. These directories contain files for the current site, for use by the system administrator when installing software locally.
~/.emacs.d/ on the other hand contains files for the current user, and is independent of system-wide changes. This makes it the best choice for storing your personal changes. Installing all packages in a sub-directory of
~/.emacs.d/ also makes it very easy to move them along with your configuration to a different machine.
First, check the value of your
‘load-path’ by asking for help on the variable:
‘C-h v load-path RET’ should give you the documentation for the variable and its current value. If your directory is not listed, you must add it (see above).
If your directory is listed, check for ConflictingLibraries.
To see the path where Emacs finds a library use