Next: Package Statuses, Up: Emacs Lisp Packages   [Contents][Index]

50.1 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). See Package Statuses.
• Which package archive this package is from, if you have more than one package archive enabled.
• A short description of the package.

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

The main command to use in the package list buffer is the x command. If the package under point isn’t installed already, this command will install it. If the package under point is already installed, this command will delete it.

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 Emacs Lisp 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 and Directory Layout, for information about what package deletion entails.

w ¶

Open the package website on the current line in a browser (package-browse-url). browse-url is used to open the browser.

~ ¶

Mark all obsolete packages for deletion (package-menu-mark-obsolete-for-deletion). This marks for deletion all the packages whose status is ‘obsolete’.

u ¶

DEL

Remove any installation or deletion mark previously added to the current line by an i or d command (package-menu-mark-unmark).

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 (marked with status ‘obsolete’). By default, this won’t mark built-in packages for which a newer version is available, but customizing package-install-upgrade-built-in can change that. See Package Installation. If you customize package-install-upgrade-built-in to a non-nil value, be sure to review all the built-in packages the U command marks, to avoid updating built-in packages you don’t want to overwrite.

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. If no packages are marked, this command will install the package under point (if it isn’t installed already), or delete the package under point (if it’s already installed).

g

r ¶

Refresh the package list (revert-buffer). This fetches the list of available packages from the package archive again, and redisplays the package list.

H ¶

Hide packages whose names match a regexp (package-menu-hide-package). This prompts for a regexp, and then hides the packages with matching names. The default value of the regexp will hide only the package whose name is at point, so just pressing RET to the prompt will hide the current package.

( ¶

Toggle visibility of old versions of packages and also of versions from lower-priority archives (package-menu-toggle-hiding).

/ a ¶

Filter package list by archive (package-menu-filter-by-archive). This prompts for a package archive (e.g., ‘gnu’), then shows only packages from that archive. You can specify several archives by typing their names separated by commas.

/ d ¶

Filter package list by description (package-menu-filter-by-description). This prompts for a regular expression, then shows only packages with descriptions matching that regexp.

/ k ¶

Filter package list by keyword (package-menu-filter-by-keyword). This prompts for a keyword (e.g., ‘games’), then shows only packages with that keyword. You can specify several keywords by typing them separated by commas.

/ N ¶

Filter package list by name or description (package-menu-filter-by-name-or-description). This prompts for a regular expression, then shows only packages with a name or description matching that regexp.

/ n ¶

Filter package list by name (package-menu-filter-by-name). This prompts for a regular expression, then shows only packages with names matching that regexp.

/ s ¶

Filter package list by status (package-menu-filter-by-status). This prompts for one or more statuses (e.g., ‘available’, see Package Statuses), then shows only packages with matching status. You can specify several status values by typing them separated by commas.

/ v ¶

Filter package list by version (package-menu-filter-by-version). This prompts first for one of the comparison symbols ‘<’, ‘>’ or ‘=’ and for a version string, and then shows packages whose versions are correspondingly lower, equal or higher than the version you typed.

/ m ¶

Filter package list by non-empty mark (package-menu-filter-marked). This shows only the packages that have been marked to be installed or deleted.

/ u ¶

Filter package list to show only packages for which there are available upgrades (package-menu-filter-upgradable). By default, this filter excludes the built-in packages for which a newer version is available, but customizing package-install-upgrade-built-in can change that. See Package Installation.

/ / ¶

Clear filter currently applied to the package list (package-menu-filter-clear).

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

Next: Package Installation, Previous: The Package Menu Buffer, Up: Emacs Lisp Packages   [Contents][Index]

50.2 Package Statuses ¶

A package can have one of the following statuses:

‘available’

The package is not installed, but can be downloaded and installed from the package archive.

‘avail-obso’

The package is available for installation, but a newer version is also available. Packages with this status are hidden by default.

‘built-in’ ¶

The package is included in Emacs by default. It cannot be deleted through the package menu, and by default is not considered for upgrading (but you can change that by customizing package-install-upgrade-built-in, see Package Installation).

‘dependency’

The package was installed automatically to satisfy a dependency of another package.

‘disabled’

The package has been disabled using the package-load-list variable.

‘external’

The package is not built-in and not from the directory specified by package-user-dir (see Package Files and Directory Layout). External packages are treated much like ‘built-in’ packages and cannot be deleted.

‘held’

The package is held, See Package Installation.

‘incompat’

The package cannot be installed for some reason, for example because it depends on uninstallable packages.

‘installed’

The package is installed.

‘new’

Equivalent to ‘available’, except that the package was added to the package archive since your previous invocation of M-x list-packages.

‘obsolete’

The package is an outdated installed version; in addition to this version of the package, a newer version is also installed.

Next: Package Files and Directory Layout, Previous: Package Statuses, Up: Emacs Lisp Packages   [Contents][Index]

50.3 Package Installation ¶

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, these commands will delete old installations, but you can adjust that behavior by customizing the variable package-retention-policy.

Note that package-install will not suggest to install packages that are already installed. Similarly, package-upgrade will only suggest to upgrade packages for which a newer version is available.

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.

If you are cautious when it comes to installing and upgrading packages from package archives, you can configure package-review-policy to give you a chance to review packages before installing them. By setting the user option to t, you get to review all packages (including dependencies), during which you can browse the source code, examine a diff between the downloaded package and a previous installation or read a changelog. You can also configure package-review-policy to selectively trust or distrust specific packages or archives.

By default, Emacs downloads packages from two archives: GNU ELPA and NonGNU ELPA. These are maintained by the Emacs developers and hosted by the GNU project. GNU ELPA contains GNU packages that we consider part of GNU Emacs, but are distributed separately from the core Emacs. NonGNU ELPA contains third-party packages whose copyright has not been assigned to the Free Software Foundation.³⁵

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!

User Option: package-archives ¶

The value of this variable is an alist of package archives recognized by the Emacs package manager.

Each alist element corresponds to one archive, and should have the form (id . location), where id is the name of the archive (a string) and location is its base location (a string).

If the base location starts with ‘http:’ or ‘https:’, it is treated as an HTTP(S) URL, and packages are downloaded from this archive via HTTP(S) (as is the case for the default GNU archive).

Otherwise, the base location should be a directory name. In this case, Emacs retrieves packages from this archive via ordinary file access. Such local archives are mainly useful for testing.

Emacs can suggest installing packages when you visit certain kinds of files. When you visit a file with no specific mode available, you can use the package-autosuggest command to find and install add-on ELPA packages recommended for this file type. If you enable package-autosuggest-mode, Emacs will automatically notify you if it there is a suggested add-on package for the file visited by the buffer. The default is for these notifications to display a button in the buffer window’s mode-line suggesting you to upgrade the major mode by installing add-on packages, but you can control how Emacs presents these notifications by customizing the package-autosuggest-style user option.

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. Therefore, if you customize this variable via Customize, you should save your customized setting into your early init file. To do this, set or change the value of the variable custom-file (see Saving Customizations) to point to your early init file before saving the customized value of package-enable-at-startup.

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.)

Next: Fetching Package Sources, Previous: Package Installation, Up: Emacs Lisp Packages   [Contents][Index]

50.4 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 in 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 customizing 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 The Package Menu Buffer) 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.

Previous: Package Files and Directory Layout, Up: Emacs Lisp Packages   [Contents][Index]

50.5 Fetching Package Sources ¶

By default package-install downloads a Tarball from a package archive and installs its files. This might be inadequate if you wish to hack on the package sources and share your changes with others. In that case, you may prefer to directly fetch and work on the upstream source. This often makes it easier to develop patches and report bugs.

One way to do this is to use package-vc-install, to fetch the source code for a package directly from source. The command will also automatically ensure that all files are byte-compiled and auto-loaded, just like with a regular package. Packages installed this way behave just like any other package. You can upgrade them using package-upgrade or package-upgrade-all and delete them again using package-delete. They are even displayed in the regular package listing. If you just wish to clone the source of a package, without adding it to the package list, use package-vc-checkout.

Note that currently, built-in packages cannot be upgraded using package-vc-install.

With the source checkout, you might want to reproduce a bug against the current development head or implement a new feature to scratch an itch. If the package metadata indicates how to contact the maintainer, you can use the command package-report-bug to report a bug via Email. This report will include all the user options that you have customized. If you have made a change you wish to share with the maintainers, first commit your changes then use the command package-vc-prepare-patch to share it. See Preparing Patches.

• Specifying Package Sources

;; Emacs will download BBDB's specification from GNU ELPA:
(package-vc-install 'bbdb)

;; Specifying information manually:
(package-vc-install
  '(bbdb :url "https://git.savannah.nongnu.org/git/bbdb.git"
         :lisp-dir "lisp"
         :doc "doc/bbdb.texi"))