Emacs Lisp code is stored in files whose names conventionally end in .el. Such files are automatically visited in Emacs Lisp mode.
Emacs Lisp code can be compiled into byte-code, which loads faster, takes up less space, and executes faster. By convention, compiled Emacs Lisp code goes in a separate file whose name ends in ‘.elc’. For example, the compiled code for foo.el goes in foo.elc. See Byte Compilation in the Emacs Lisp Reference Manual.
Emacs Lisp code can also be compiled into native code: machine code not unlike the one produced by a C or Fortran compiler. Native code runs even faster than byte-code. Natively-compiled Emacs Lisp code is stored in files whose names end in ‘.eln’. See Native Compilation in the Emacs Lisp Reference Manual.
To load an Emacs Lisp file, type M-x load-file. This command reads a file name using the minibuffer, and executes the contents of that file as Emacs Lisp code. It is not necessary to visit the file first; this command reads the file directly from disk, not from an existing Emacs buffer.
If an Emacs Lisp file is installed in the Emacs Lisp load path
(defined below), you can load it by typing M-x load-library,
instead of using M-x load-file. The M-x load-library
command prompts for a library name rather than a file name; it
searches through each directory in the Emacs Lisp load path, trying to
find a file matching that library name. If the library name is
‘foo’, it tries looking for files named
foo.elc, foo.el, and foo. (If
Emacs was built with native compilation enabled, load-library
looks for a ‘.eln’ file that corresponds to foo.el
and loads it instead of foo.elc.) The default behavior
is to load the first file found. This command prefers .eln
files over .elc files, and prefers .elc files over
.el files, because compiled files load and run faster. If it
finds that lib.el is newer than lib.elc, it
issues a warning, in case someone made changes to the .el file
and forgot to recompile it, but loads the .elc file anyway.
(Due to this behavior, you can save unfinished edits to Emacs Lisp
source files, and not recompile until your changes are ready for use.)
If you set the option load-prefer-newer
to a non-nil
value, however, then rather than the procedure described above, Emacs
loads whichever version of the file is newest. If Emacs was built
with native compilation, and it cannot find the ‘.eln’ file
corresponding to lib.el, it will load a
lib.elc and start native compilation of
lib.el in the background, then load the ‘.eln’ file
when it finishes compilation.
Emacs Lisp programs usually load Emacs Lisp files using the
load
function. This is similar to load-library
, but is
lower-level and accepts additional arguments. See How Programs Do
Loading in the Emacs Lisp Reference Manual.
The Emacs Lisp load path is specified by the variable
load-path
. Its value should be a list of directories
(strings). These directories are searched, in the specified order, by
the M-x load-library command, the lower-level load
function, and other Emacs functions that find Emacs Lisp libraries.
An entry in load-path
can also have the special value
nil
, which stands for the current default directory, but it is
almost always a bad idea to use this, because its meaning will depend
on the buffer that is current when load-path
is used by Emacs.
(If you find yourself wishing that nil
were in the list, most
likely what you really want is to use M-x load-file.)
The default value of load-path
is a list of directories where
the Lisp code for Emacs itself is stored. If you have libraries of
your own in another directory, you can add that directory to the load
path. Unlike most other variables described in this manual,
load-path
cannot be changed via the Customize interface
(see Easy Customization Interface), but you can add a directory to it by
putting a line like this in your init file (see The Emacs Initialization File):
(add-to-list 'load-path "/path/to/my/lisp/library")
It is customary to put locally installed libraries in the
site-lisp directory that is already in the default value of
load-path
, or in some subdirectory of site-lisp. This
way, you don’t need to modify the default value of load-path
.
Similarly to load-path
, the list of directories where Emacs
looks for *.eln files with natively-compiled Lisp code is
specified by the variable native-comp-eln-load-path
.
Some commands are autoloaded; when you run them, Emacs
automatically loads the associated library first. For instance, the
M-x compile command (see Running Compilations under Emacs) is autoloaded; if you
call it, Emacs automatically loads the compile
library first.
In contrast, the command M-x recompile is not autoloaded, so it
is unavailable until you load the compile
library.
Automatic loading can also occur when you look up the documentation
of an autoloaded command (see Help by Command or Variable Name), if the documentation
refers to other functions and variables in its library (loading the
library lets Emacs properly set up the hyperlinks in the *Help*
buffer). To disable this feature, change the variable
help-enable-autoload
to nil
.
Automatic loading also occurs when completing names for
describe-variable
and describe-function
, based on the
prefix being completed. To disable this feature, change the variable
help-enable-completion-autoload
to nil
.
Once you put your library in a directory where Emacs can find and
load it, you may wish to make it available at startup. This is useful
when the library defines features that should be available
automatically on demand, and manually loading the library is thus
inconvenient. In these cases, make sure the library will be loaded by
adding suitable forms to your init file: either load
or
require
(if you always need to load the library at startup), or
autoload
if you need Emacs to load the library when some
command or function is invoked. For example:
;; Loads my-shining-package.elc unconditionally. (require 'my-shining-package)
;; Will load my-shining-package.elc when my-func
is invoked.
(autoload 'my-func "my-shining-package")
Note that installing a package using package-install
(see Package Installation) takes care of placing the package’s
Lisp files in a directory where Emacs will find it, and also writes
the necessary initialization code into your init files, making the
above manual customizations unnecessary.