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 URL 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 in Emacs EasyPG Assistant Manual). 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 subdirectory of
package-user-dir, which causes Emacs to invoke GnuPG with the option ‘
--homedir’ when verifying signatures. If
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-
nil, Emacs attempts to verify signatures when you install packages. If the option has the value
allow-unsigned, and a usable OpenPGP configuration is found, signed packages will be checked, but 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
package-unsigned-archives. (If the value is
allow-unsigned and no usable OpenPGP is found, this option is treated as if its value was
nil.) If the value is
t, at least one signature must be valid; if the value is
all, all of them must be valid.
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 enabled is
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 made available to the current Emacs session. Making a package available 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.
After a package is installed, it is automatically made available by Emacs in all subsequent sessions. This happens at startup, before processing the init file but after processing the early init file (see Early Init File). As an exception, Emacs does not make packages available at startup if invoked with the ‘
-q’ or ‘
--no-init-file’ options (see Initial Options).
To keep Emacs from automatically making packages available at startup, change the variable
nil. You must do this in the early init file, as the variable is read before loading the regular init file. Currently this variable cannot be set via Customize.
If you have set
nil, you can still make packages available either during or after startup. To make installed packages available during startup, call the function
package-activate-all in your init file. To make installed packages available after startup, invoke the command
M-: (package-activate-all) RET.
For finer control over which packages are made available at startup, 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 make available version
version of the package named
version should be a version string (corresponding to a specific version of the package), or
t (which means to make available any installed version), or
nil (which means no version; this disables the package, preventing it from being made available). A list element can also be the symbol
all, which means to make available the latest installed version of any package not named by the other list elements. The default value is just
For example, if you set
'((muse "3.20") all), then Emacs only makes available 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 ‘