Packages are most conveniently installed using the package menu (see The Package Menu Buffer), 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. Similarly, if you want to upgrade a package, you can use the M-x package-upgrade command, and if you want to upgrade all the packages, you can use the M-x package-upgrade-all command.
By default, package-install doesn’t consider built-in
packages for which new versions are available from the archives. (A
package is built-in if it is included in the Emacs distribution.) In
particular, it will not show built-in packages in the list of
completion candidates when you type at its prompt. But if you invoke
package-install with a prefix argument, it will also consider
built-in packages that can be upgraded. You can make this behavior
the default by customizing the variable
package-install-upgrade-built-in: if its value is
non-nil, package-install will consider built-in packages
even when invoked without a prefix argument. Note that the
package-menu commands (see The Package Menu Buffer) are also affected by
package-install-upgrade-built-in.
By contrast, package-upgrade and package-upgrade-all
never consider built-in packages. If you want to use these commands
for upgrading some built-in packages, you need to upgrade each of
those packages, once, either via C-u M-x package-install
RET, or by customizing package-install-upgrade-built-in
to a non-nil value, and then upgrading the package once via the
package menu or by package-install.
If you customize package-install-upgrade-built-in to a
non-nil value, be very careful when using commands that update
many packages at once, like package-upgrade-all and U in
the package menu: those might overwrite built-in packages that you
didn’t intent to replace with newer versions from the archives. Don’t
use these bulk commands if you want to update only a small number of
built-in packages.
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 package-gnupghome-dir is 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.
For more information on cryptographic keys and signing, see GnuPG in The GNU Privacy Guard Manual. Emacs comes with an interface to GNU Privacy Guard, see EasyPG in Emacs EasyPG Assistant Manual.
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 package-menu-hide-low-priority.)
Once a package is downloaded, byte-compiled 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.
Installed packages are 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 The 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 package-enable-at-startup to
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 many packages installed, you can improve startup times
by setting the user option package-quickstart to t.
Setting this option will make Emacs precompute many things instead of
re-computing them on every Emacs startup. However, if you do this,
then you have to manually run the command
package-quickstart-refresh when the activations need to be
changed, such as when you change the value of
package-load-list.
If you have set package-enable-at-startup to 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 name. Here, 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 '(all).
For example, if you set package-load-list to '((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 ‘held’ status.
Emacs byte code is quite stable, but it’s possible for byte code to become outdated, or for the compiled files to rely on macros that have changed in new versions of Emacs. You can use the command M-x package-recompile to recompile a particular package, or M-x package-recompile-all to recompile all the packages. (The latter command might take quite a while to run if you have many installed packages.)