Emacs Lisp Packages
*******************

Emacs includes a facility that lets you easily download and install packages that implement additional features.  Each package is a separate Emacs Lisp program, sometimes including other components such as an Info manual.

M-x list-packages brings up a buffer named *Packages* with a list of all packages.  You can install or uninstall packages via this buffer.  See Package Menu.

The command C-h P (describe-package) prompts for the name of a package, and displays a help buffer describing that attributes of the package and the features that it implements.

By default, Emacs downloads packages from a package archive maintained by the Emacs developers and hosted by the GNU project. Optionally, you can also download packages from archives maintained by third parties.  See Package Installation.

For information about turning an Emacs Lisp program into an installable package, see Packaging (The Emacs Lisp Reference Manual).  For information about finding third-party packages and other Emacs Lisp extensions, see Packages that do not come with Emacs (GNU Emacs FAQ).

The Package Menu Buffer
=======================

The command M-x list-packages brings up the package menu. This is a buffer listing all the packages that Emacs knows about, one on each line, with the following information:

  * The package name (e.g. auctex).

  * The package's version number (e.g. 11.86).

  * The package's status---normally one of available (can be downloaded from the package archive), installed, or built-in (included in Emacs by default).

     In some instances, the status can be held, disabled, or obsolete.  See Package Installation.

  * A short description of the package.

The list-packages command accesses the network, to retrieve the list of available packages from the package archive server.  If the network is unavailable, it falls back on the most recently retrieved list.

The following commands are available in the package menu:

h
     Print a short message summarizing how to use the package menu (package-menu-quick-help).

?
RET
     Display a help buffer for the package on the current line (package-menu-describe-package), similar to the help window displayed by the C-h P command (see Packages).

i
     Mark the package on the current line for installation (package-menu-mark-install).  If the package status is available, this adds an I character to the start of the line; typing x (see below) will download and install the package.

d
     Mark the package on the current line for deletion (package-menu-mark-delete).  If the package status is installed, this adds a D character to the start of the line; typing x (see below) will delete the package. See Package Files, for information about what package deletion entails.

u
     Remove any installation or deletion mark previously added to the current line by an i or d command.

U
     Mark all package with a newer available version for ``upgrading'' (package-menu-mark-upgrades).  This places an installation mark on the new available versions, and a deletion mark on the old installed versions.

x
     Download and install all packages marked with i, and their dependencies; also, delete all packages marked with d (package-menu-execute).  This also removes the marks.

r
     Refresh the package list (package-menu-refresh).  This also retrieves the list of available packages from the package archive again.

For example, you can install a package by typing i on the line listing that package, followed by x.

Package Installation
====================

Packages are most conveniently installed using the package menu (see Package Menu), but you can also use the command M-x package-install.  This prompts for the name of a package with the available status, then downloads and installs it.

A package may require certain other packages to be installed, because it relies on functionality provided by them.  When Emacs installs such a package, it also automatically downloads and installs any required package that is not already installed.  (If a required package is somehow unavailable, Emacs signals an error and stops installation.)  A package's requirements list is shown in its help buffer.

By default, packages are downloaded from a single package archive maintained by the Emacs developers.  This is controlled by the variable package-archives, whose value is a list of package archives known to Emacs.  Each list element must have the form (ID . LOCATION), where ID is the name of a package archive and LOCATION is the HTTP address or directory name of the package archive.  You can alter this list if you wish to use third party package archives---but do so at your own risk, and use only third parties that you think you can trust!

Once a package is downloaded and installed, it takes effect in the current Emacs session.  What ``taking effect'' means depends on the package; most packages just make some new commands available, while others have more wide-ranging effects on the Emacs session.  For such information, consult the package's help buffer.

By default, Emacs also automatically loads all installed packages (causing them to ``take effect'') in subsequent Emacs sessions.  This happens at startup, after processing the init file (see Init File).  As an exception, Emacs does not load packages at startup if invoked with the -q or --no-init-file options (see Initial Options).

To disable automatic package loading, change the variable package-enable-at-startup to nil.  If you do this, you can use the command M-x package-initialize to load your packages.

For finer control over package loading, you can use the variable package-load-list.  Its value should be a list.  A list element of the form (NAME VERSION) tells Emacs to load version VERSION of the package named NAME.  Here, VERSION should be a version string (corresponding to a specific version of the package), or t (which means to load any installed version), or nil (which means no version; this ``disables'' the package, preventing it from being loaded).  A list element can also be the symbol all, which means to load the latest installed version of any package not named by the other list elements.  The default value is just '(all).

For example, if you set package-load-list to '((muse "3.20") all), then Emacs only loads version 3.20 of the muse package, plus any installed version of packages other than muse.  Any other version of muse that happens to be installed will be ignored.  The muse package will be listed in the package menu with the held status.

Package Files and Directory Layout
==================================

Each package is downloaded from the package archive in the form of a single package file---either an Emacs Lisp source file, or a tar file containing multiple Emacs Lisp source and other files.  Package files are automatically retrieved, processed, and disposed of by the Emacs commands that install packages.  Normally, you will not need to deal directly with them, unless you are making a package (see Packaging (The Emacs Lisp Reference Manual)).  Should you ever need to install a package directly from a package file, use the command M-x package-install-file.

Once installed, the contents of a package are placed in a subdirectory of ~/.emacs.d/elpa/ (you can change the name of that directory by changing the variable package-user-dir).  The package subdirectory is named NAME-VERSION, where NAME is the package name and VERSION is its version string.

In addition to package-user-dir, Emacs looks for installed packages in the directories listed in package-directory-list. These directories are meant for system administrators to make Emacs packages available system-wide; Emacs itself never installs packages there.  The package subdirectories for package-directory-list are laid out in the same way as in package-user-dir.

Deleting a package (see Package Menu) involves deleting the corresponding package subdirectory.  This only works for packages installed in package-user-dir; if told to act on a package in a system-wide package directory, the deletion command signals an error.