EmacsWiki: ELPA

ELPA

ELPA is the Emacs Lisp Package Archive, written originally by TomTromey. It is included in GnuEmacs, starting with version 24. package.el is the package manager library for ELPA.

“Our goal is to make it simple to install, use, and upgrade Emacs Lisp packages. We supply package.el a simple package manager for Emacs, and a repository of pre-packed Emacs Lisp code.”

See InstallingPackages for basic usage information.

Package repositories

package.el supports multiple ELPA repositories. Sometimes “ELPA” is used to refer to an ELPA repository.

GnuELPA - The GNU ELPA repository contains FSF-sanctioned Emacs packages. It is the default repository used by package.el. Starting with Emacs 28.1, the NonGNU ELPA repository is also enabled by default. The following examples show how to add the MELPA repository, in addition to GNU ELPA.

Add this to your init file:

(add-to-list 'package-archives '("melpa" . "https://melpa.org/packages/"))

Package archives may also be local to your machine.

You can also add repositories one at a time:

(add-to-list 'package-archives '("gnu" . "https://elpa.gnu.org/packages/")) ;; installed by default
(add-to-list 'package-archives '("nongnu" . "https://elpa.nongnu.org/nongnu/")) ;; installed by default from Emacs 28 onwards
(add-to-list 'package-archives '("melpa" . "https://melpa.org/packages/"))
;;; (add-to-list 'package-archives '("org" . "http://orgmode.org/elpa/") t)
;;; deprecated for Org versions >= 9.5: see https://orgmode.org/elpa.html

You can also customize option ‘package-archives’:

M-x customize-variable [RET] package-archives [RET]

You get a UI and then you can add the archives directly:

Hide Package Archives:
INS DEL Archive name: gnu
            URL or directory name: https://elpa.gnu.org/packages/
INS
    State : SAVED and set.
   An alist of archives from which to fetch. Hide
   The default value points to the GNU Emacs package repository.

Contributing to GNU ELPA

Package authors may wish to contribute their packages to the GNU ELPA repository.

The first and main step is to complete your FSF copyright assignment to cover changes to Emacs, and to make sure that all significant contributors to the package have done the same. Accordingly, you will also want to change your files’s headers to state that the copyright now belongs to the FSF (you can copy what you see in any of Emacs’s own files).

Then send an email to the emacs-devel mailing-list proposing inclusion of your package into GNU ELPA, providing the URL of the Git repository where you keep it. You can choose to use GNU ELPA’s own Git repository (git://git.sv.gnu.org/emacs/elpa.git) to host your package, but even so, you will want to send a URL pointing to the Git repository from which to clone your package.

You might also want to look at the details of MakingPackages for ELPA.

Contributing to other package repositories

There are varying degrees of difficulty and hoops to contribute to MELPA.

How Packages work in Emacs 24

The Elisp Manual describes how the package system is initialized:

: Whenever Emacs starts up, it automatically calls the function ‘package-initialize’ to load installed packages. This is done after loading the init file and abbrev file (if any) and before running ‘after-init-hook’ (see Startup Summary). Automatic package loading is disabled if the user option package-enable-at-startup is nil.

So packages are initialized AFTER the init.el is loaded. This means you should NOT put package specific initialization into your init.el except in a few ways:

customization variables for a package are fine; they can be set before a package has loaded
auto-mode-alist changes can be made in a way that does not require the package to be loaded before they are setup:

    (add-to-list 'auto-mode-alist '("\\.gradle" . groovy-mode))

mode specific customization of a package could go in a package hook which can be set before the package is loaded, for example:

    (add-hook 'groovy-mode-hook (lambda () (setq tab-width 4)))

key bindings can also be done in such a way to not cause init failure, even if the package is not loaded:

    (global-set-key (kbd "C-'")     'shell-switcher-switch-buffer)

some package specific initialization can be done with eval-after-load, see eval-after-load
it could be easier just to move package-initialize to another point during startup so you can (require) ELPA packages; this takes care of a lot of the described issues:

    ;; basic initialization, (require) non-ELPA packages, etc.
    (setq package-enable-at-startup nil)
    (package-initialize)
    ;; (require) your ELPA packages, configure them as normal

if all these tricks don’t work you can still postpone config until after the packages have been loaded like this:

    (add-hook 'after-init-hook 'cycbuf-init)

Using the `after-init-hook' for package config

Some people think that using after-init-hook seems like a last resort because it may force the load of the package you’re referring to (thus slowing down Emacs). Others point out that moving your whole initialization to after ELPA is loaded makes things easier to use.

You can do that by putting this in your init file:

(add-hook 'after-init-hook (lambda () (load "<real init file>")))

and moving all your normal init to the <<real init file>>.

Using `eval-after-load' for package config

Using ‘eval-after-load’ is one way of achieving fine grained configuration per-package. It falls back gracefully if the package is not present.

The following code is an example of customizing a hypothetical major mode called abcd-mode using eval-after-load:

    (eval-after-load "abcd-mode" ; <-- "abcd-mode", not 'abcd-mode
      '(progn
         (setq-default abcd-basic-offset 7) ; setting some option
         (add-to-list 'abcd-globals-list "console") ; appending to a list option
         (add-hook 'abcd-mode-hook 'prepare-some-abcd-soup) ; things to do for abcd mode buffers
         (define-key abcd-mode-map (kbd "C-c C-c") 'play-some-abcd-song) ; add some key binding for abcd mode
     ))

And here is an example for a hypothetical global minor mode called broccoli mode.

    (eval-after-load "broccoli-autoloads" ; <-- "broccoli-autoloads", not "broccoli"
      '(progn
         (if (require 'broccoli nil t)
             (progn
               (broccoli-mode 1) ; Turn on Broccoli global minor mode if broccoli-autoloads.el doesn't do it.
               (setq-default broccoli-how 'steamed) ; set some option.
               (add-to-list 'broccoli-additional-stuff 'salt) ; add to a list option.
               )
           (warn "broccoli is not found."))))

Using `with-eval-after-load' for package config

Starting in emacs 24.4, ‘with-eval-after-load’ is simpler than ‘eval-after-load’:

    (with-eval-after-load 'abcd-mode
       (setq-default abcd-basic-offset 7) ; setting some option
       (add-to-list 'abcd-globals-list "console") ; appending to a list option
       (add-hook 'abcd-mode-hook 'prepare-some-abcd-soup) ; things to do for abcd mode buffers
       (define-key abcd-mode-map (kbd "C-c C-c") 'play-some-abcd-song) ; add some key binding for abcd mode
     )

I (who?) didn’t see anything here about actually using the program (what program?). After setting variable ‘package-archives’ via the instructions above, refresh the repository via ‘M-x package-refresh-contents’.

Then to install a program, for example ‘geiser’, use: ‘M-x package-install RET geiser’. (Note package geiser requires the Marmalade repo.)

Another hint, if the installed package doesn’t seem to work, is to confirm that the package is actually installed, using ‘package-list-packages’. Search for the package name. The reason I added this step was that I had used install a few times before it actually was verified as installed, after which it worked. During each installation, I got a question about saving the contents to a local file, and I’m not sure what that was about. But in the end, I was able to get this running. [[Who?]]

ELPA policy

ELPA policy for Emacs 24 was discussed here: http://thread.gmane.org/gmane.emacs.devel/132634/focus=132640

Downgrading to an earlier version of a package

Suppose that Auctex 11.88 complains about TeX-auto-add-type . One lazy solution is to downgrade to an earlier version. If auctex 11.88 came from elpa, go to https://elpa.gnu.org/packages/ and then to auctex and download the tar file of the latest version of auctex 11.87 and save it under your elpa archives (~/.emacs.d/elpa/auctex-11.87.7.tar). Then suppress the 11.88 with list-package, marking d on auctex and x to execute the deletion.

Now, type the command ‘package-install-file’ and load file ~/.emacs.d/elpa/auctex-11.87.7.tar . The tar file must contain a -pkg.el file which is the cas from the elpa.gnu.org site.

(Note: Auctex 11.88 from gnu archives works fine for me. Only auctex from melpa complains about TeX-auto-add-type.)

How packages work in Emacs 23

You can make packages work in Emacs 23. Add something like this to your init.el:

(require 'package)
;; Any add to list for package-archives (to add marmalade or melpa) goes here, e.g.:
(add-to-list 'package-archives
    '("marmalade" .
      "https://marmalade-repo.org/packages/"))
(package-initialize)

The following package.el version must be placed in one of the directories in your load path: https://git.savannah.gnu.org/gitweb/?p=emacs.git;a=blob_plain;hb=ba08b24186711eaeb3748f3d1f23e2c2d9ed0d09;f=lisp/emacs-lisp/package.el

In case Emacs 23 shows this error at startup: File error: Cannot load file, package, a solution to this error message is to add the following code to your Emacs init file, and of course to make sure the version of package.el noted above is :

(when
    (load
     (expand-file-name "~/.emacs.d/package.el")))

(Idea is from http://ergoemacs.org/emacs/emacs23_install_elpa.html)

Other Repositories

AndrewHyatt has written an implementation of ELPA for AppEngine, written in Go. It is not yet running publicly yet, as of April 2013.

The source code for Marmalade is available on GitHub. It is a complete EmacsLisp project, an Elnode webapp.

Create Local Repositories

https://github.com/redguardtoo/elpa-mirror creates a local fallback repository from installed packages.

For example, you successfully installed all the packages from https://melpa.org at home computer. You can run command `M-x elpamr-create-mirror-for-installed` to create a local repository which containing all the packages you are using.

At office computer you can use that local repository to install packages if corp firewall blocks https://melpa.org

CategoryCode CategoryPackaging