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
package-archives, whose value is a list of package
archives known to Emacs. Each list element must have the form
), where id is the name of a
package archive and location is the HTTP address or
name of the package archive directory. 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!
The maintainers of package archives can increase the trust that you
can have in their packages by signing them. They generate a
private/public pair of cryptographic keys, and use the private key to
create a signature file for each package. With the public key, you
can use the signature files to verify the package creator and make sure
the package has not been tampered with. Signature verification uses
the GnuPG package via the EasyPG
interface (see EasyPG).
A valid signature is not a cast-iron
guarantee that a package is not malicious, so you should still
exercise caution. Package archives should provide instructions
on how you can obtain their public key. One way is to download the
key from a server such as https://pgp.mit.edu/.
Use M-x package-import-keyring to import the key into Emacs.
Emacs stores package keys in the directory specified by the variable
package-gnupghome-dir, by default in the gnupg
package-user-dir, which causes Emacs to invoke
GnuPG with the option ‘--homedir’ when verifying signatures.
nil, GnuPG's option
‘--homedir’ is omitted.
The public key for the GNU package archive is distributed with Emacs,
in the etc/package-keyring.gpg. Emacs uses it automatically.
If the user option
package-check-signature is non-
Emacs attempts to verify signatures when you install packages. If the
option has the value
allow-unsigned, you can still install a
package that is not signed. If you use some archives that do not sign
their packages, you can add them to the list
For more information on cryptographic keys and signing, see GnuPG. Emacs comes with an interface to GNU Privacy Guard, see EasyPG.
If you have more than one package archive enabled, and some of them
offer different versions of the same package, you may find the option
package-pinned-packages useful. You can add package/archive
pairs to this list, to ensure that the specified package is only ever
downloaded from the specified archive.
Another option that is useful when you have several package archives
package-archive-priorities. It specifies the
priority of each archive (higher numbers specify higher priority
archives). By default, archives have the priority of zero, unless
specified otherwise by this option's value. Packages from
lower-priority archives will not be shown in the menu, if the same
package is available from a higher-priority archive. (This is
controlled by the value of
Once a package is downloaded and installed, it is loaded into
the current Emacs session. Loading a package is not quite the same as
loading a Lisp library (see Lisp Libraries); loading a package
adds its directory to
load-path and loads its autoloads. The
effect of a package's autoloads varies from package to 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 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
The reason automatic package loading occurs after loading the init
file is that user options only receive their customized values after
loading the init file, including user options which affect the
packaging system. In some circumstances, you may want to load
packages explicitly in your init file (usually because some other code
in your init file depends on a package). In that case, your init file
should call the function
package-initialize. It is up to you
to ensure that relevant user options, such as
(see below), are set up prior to the
This will automatically set
avoid loading the packages again after processing the init file.
Alternatively, you may choose to completely inhibit package loading at
startup, and invoke the command M-x package-initialize to load
your packages manually.
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
) 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
For example, if you set
"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.