Emacs Lisp packages and autoloads

Emacs Lisp has no import statement. A library is a file that Emacs finds by name on a search path and runs with load, and a feature is a symbol that says the library has been loaded. Autoloads let Emacs know a function without loading its file, and the package system (package.el) downloads libraries from archives and arranges both. This page describes the mechanisms and the file formats of packages and archives.

Features

Form	Meaning
`(provide 'NAME)`	say that the feature NAME is present; normally the last form of the library. It adds the symbol to the variable `features`.
`(require 'NAME &optional FILENAME NOERROR)`	load the library unless the feature is present. FILENAME is the file to load instead of one named like the feature. A non-`nil` NOERROR returns `nil` instead of signalling an error when the file is missing. It signals an error as well when the file loads but does not provide the feature.
`(featurep 'NAME)`	true when the feature is present
`(with-eval-after-load FILE BODY…)`	run BODY after FILE (or a feature) has been loaded; at once if it already was. `eval-after-load` is the function form.

(require 'subr-x)
(when (require 'magit nil t)
  (keymap-global-set "C-x g" #'magit-status))
(with-eval-after-load 'dired
  (keymap-set dired-mode-map "e" #'wdired-change-to-wdired-mode))
(provide 'my-library)

How load finds a file

(load FILE &optional NOERROR NOMESSAGE NOSUFFIX MUST-SUFFIX) looks for FILE in the directories of load-path (absolute names and names starting with ./ skip the search). In each directory it tries every suffix; the first file found is loaded. load-file loads one named file without a search.

Variable	Meaning
`load-path`	the list of directories to search
`load-suffixes`	normally `(".elc" ".el")`; with dynamic modules, the suffixes of shared libraries (`.so`, `.dll`, `.dylib`) are in `module-file-suffix` and are tried as well
`load-file-rep-suffixes`	other representations of the same file; `("")`, plus `".gz"` when Auto Compression mode is on
`load-prefer-newer`	non-`nil` makes `load` test all suffixes and take the newest file, so a newer `.el` beats an older `.elc`; the default is `nil`, which takes the first found
`load-in-progress`, `load-file-name`	true during a load, and the name of the file being loaded
`load-history`	an alist of loaded files, each with the functions and variables it defined
`native-comp-eln-load-path`	where compiled `.eln` files are looked for; see Native compilation

locate-library NAME returns the file that load would use. A choice between .elc and .el is made by suffix order, so a stale .elc is loaded in preference to a newer source, unless load-prefer-newer is set (Byte-compilation). The order in which the files of a user’s start-up are loaded is on File structure.

Autoloads

An autoload is a function definition that stands for a function defined in another file. When it is called, Emacs loads the file and runs the real definition.

(autoload 'my-command "my-library" "Do the thing." t)

The arguments are (autoload FUNCTION FILE &optional DOCSTRING INTERACTIVE TYPE): the file to load, the documentation string (so that help works), whether the function is a command (t, or a list of modes) and the type of the definition, which is nil for a function, t or macro for a macro and keymap for a keymap. autoloadp tests whether an object is an autoload object, which is a list (autoload FILE DOC INTERACTIVE TYPE).

Most autoloads are generated. A cookie ;;;###autoload before a definition marks it (File structure), and these functions make the file of autoload forms:

Function	Use
`make-directory-autoloads DIR OUTPUT-FILE`	collect the autoloads of the Lisp files in DIR into OUTPUT-FILE (Emacs 28; it replaces `update-directory-autoloads`)
`loaddefs-generate DIRS OUTPUT-FILE &optional EXCLUDED-FILES EXTRA-DATA INCLUDE-PACKAGE-VERSION GENERATE-FULL`	the same from a list of directories; it does not descend into subdirectories. The library `loaddefs-gen` is the generator.
`generated-autoload-file`	a variable, which a source file may set as a file-local variable to ask for its autoloads to go to another file

package.el

The library package.el installs libraries from package archives. At start-up Emacs reads the installed packages and activates them (adds them to load-path and loads their -autoloads.el file), unless package-enable-at-startup is nil.

Name	Use
`package-archives`	an alist of `(NAME . LOCATION)`. The default has `"gnu"` (`https://elpa.gnu.org/packages/`) and `"nongnu"` (`https://elpa.nongnu.org/nongnu/`). MELPA is added by the user, as `("melpa" . "https://melpa.org/packages/")`.
`package-initialize`	read and activate the installed packages; called at start-up automatically
`package-activate-all`	activate every installed package
`package-refresh-contents`	download the archive-contents of each archive
`package-install`	install a package and its dependencies; a package that is listed by `package-selected-packages` is one that the user asked for
`package-install-selected-packages`	install what is in `package-selected-packages`
`package-user-dir`	the directory of installed packages, `elpa` in the user’s Emacs directory
`package-check-signature`	whether to check `.sig` files; the default is `allow-unsigned`
`package-pinned-packages`	an alist of packages that are taken only from one archive
`package-quickstart`, `package-quickstart-file`	when `package-quickstart` is non-`nil`, activation reads one precomputed file (`package-quickstart.el`), which `package-quickstart-refresh` rebuilds
`package-vc-install` and related commands	install a package from its version-control repository (Emacs 29); `package-vc-selected-packages` records them

(setq package-archives
      '(("gnu"    . "https://elpa.gnu.org/packages/")
        ("nongnu" . "https://elpa.nongnu.org/nongnu/")
        ("melpa"  . "https://melpa.org/packages/")))
(package-refresh-contents)
(package-install 'dash)

GNU ELPA and NonGNU ELPA are the two archives that Emacs knows; the first needs a copyright assignment of its authors, the second does not. MELPA is a separate archive that builds packages from their repositories.

Package formats

Single-file package

A single NAME.el file. The first line gives the name and the description (;;; NAME.el --- DESCRIPTION), and the headers give the rest: Version (or Package-Version, which wins), and Package-Requires for dependencies, a list of (NAME "VERSION") in which emacs stands for the Emacs version. Keywords and URL are optional. See File structure for the headers. The archive stores the file as NAME-VERSION.el.

Multi-file package

A tar file named NAME-VERSION.tar. All its files extract into one directory NAME-VERSION, which must hold NAME-pkg.el: a single call of define-package.

(define-package "superfrobnicator" "1.3"
  "Frobnicate and bifurcate flanges"
  '((emacs "27.1") (flange "1.0"))
  :keywords '("multimedia")
  :url "https://example.com/jrhacker/superfrobnicator")

The arguments are the name and the version (strings), the description, and the requirements, which are (NAME "VERSION") pairs; later come keyword and value pairs. If the directory has a README, it is the long description. A file named dir is an Info directory made by install-info, and the directory is added to Info-directory-list when the package is activated. Installing generates NAME-autoloads.el in the directory. A single-file package is also installed into its own directory, and a package directory has the form NAME-VERSION in package-user-dir.

The archive-contents file

An archive is a directory on a web server (or a file system). It holds the package files, a signature file NAME-VERSION.tar.sig or NAME-VERSION.el.sig beside each one if signed (an OpenPGP detached signature; archive-contents.sig signs the list), and a file named archive-contents. This file is one Lisp list that package.el reads with read. Its first element is the archive format version, which is 1; the other elements are the packages:

(1
 (superfrobnicator . [(1 3) ((emacs (27 1)) (flange (1 0)))
                      "Frobnicate and bifurcate flanges" tar
                      ((:url . "https://example.com/jrhacker/superfrobnicator")
                       (:keywords "multimedia"))])
 (flange . [(1 0) nil "Flange library" single nil]))

Slot of the vector	Content
1	the version as a list of integers, `(1 3)`, not as a string
2	the requirements: a list of `(NAME VERSION-LIST)`, or `nil`
3	the description string
4	the kind: `single` for a `.el` file, `tar` for a tar archive
5	the extras, an alist such as `(:url . "…")`, `(:keywords "…")`, `(:authors …)`, `(:maintainer …)`, `(:commit "…")`; it may be missing from the old four-slot files

An archive with a version number greater than package-archive-version is rejected. When Emacs downloads an archive it keeps the file under archives/NAME/ in package-user-dir. An installed package that came from a directory has the kind dir in Emacs, which never appears in the archive file.

use-package

use-package is part of Emacs from version 29. It groups what one package needs into a single declaration.

(use-package magit
  :ensure t
  :defer t
  :bind (("C-x g" . magit-status))
  :custom (magit-diff-refine-hunk 'all)
  :config (setq magit-save-repository-buffers 'dontask))

Keyword	Effect
`:ensure`	install the package from an archive if it is missing (with a name, install that one)
`:pin`	take the package from the named archive
`:defer`	do not load the package at start-up; the keywords that make autoloads imply it
`:demand`	load it at once, even when the keywords would delay it
`:init`	forms run before the package is loaded
`:config`	forms run after the package is loaded
`:bind`	key bindings, as `("KEY" . command)`; they create autoloads for the commands
`:hook`	add a function to a hook; `(mode . function)` gives `mode-hook`
`:custom`, `:custom-face`	set user options and faces through Customize
`:mode`, `:interpreter`	add entries to `auto-mode-alist` and `interpreter-mode-alist`
`:commands`	autoloads for the named commands
`:after`	load the declaration after other packages have loaded
`:if`, `:when`, `:unless`	load the declaration only when the condition holds
`:load-path`	directories to add to `load-path`
`:diminish`, `:delight`	shorten or hide the mode-line name of a mode (they use the packages of the same names)
`:vc`	install from a version-control repository (Emacs 30)

Cask

Cask is a separate tool for developing a package. Its Cask file is Emacs Lisp that is evaluated with a few special forms:

(source gnu)
(source melpa)

(package "my-package" "0.1.0" "A short description")
(package-file "my-package.el")
(files "*.el")

(depends-on "dash" "2.19.1")

(development
 (depends-on "ert-runner"))

The forms are source (an archive by name), package (name, version, description), package-file (the file whose headers describe the package), files (the file patterns that belong to it), depends-on (a package, with an optional version) and development (dependencies only for development). package-descriptor names a -pkg.el file that holds the description.

Shorthands

The variable read-symbol-shorthands (Emacs 28), set in a file-local variables list, is an alist of (SHORT . LONG) prefixes. When the reader meets a symbol that starts with SHORT, it replaces that part with LONG, so a library can write my- for a long package prefix. It applies to symbols as read, so the stored names are the long ones.

;; Local Variables:
;; read-symbol-shorthands: (("m-" . "my-long-package-"))
;; End:

Not described

Known, not yet covered

Reference: Eask and other package tools, the build recipes of MELPA, package-build, the .dir-locals.el files in packages, and the package-vc commands are named or omitted. Cask’s forms are listed from its documented use and not checked against its source.
Reference: dynamic modules (shared libraries loaded with module-load, using emacs-module.h) are named only; see Processes.
Reference: the format of the generated loaddefs.el, the cookie variants (;;;###autoload with a form after it) and the load-time details of load-history entries are summarised.

.EL File Format – Packages and autoloads