Getting started

Installing Melpa

To use the MELPA repository, you'll need an Emacs with package.el and TLS support, ie. Emacs 24.1 or greater. To test TLS support you can visit a HTTPS URL, for example with M-x eww RET https://wikipedia.org RET.

Consider using Emacs 26.3 or greater; otherwise you will have to add a kludge to work around a bug described in Known Issues below.

Enable installation of packages from MELPA by adding an entry to package-archives after (require 'package) and before the call to package-initialize in your init.el or .emacs file:

(require 'package)
(add-to-list 'package-archives '("melpa" . "https://melpa.org/packages/") t)
;; Comment/uncomment this line to enable MELPA Stable if desired.  See `package-archive-priorities`
;; and `package-pinned-packages`. Most users will not need or want to do this.
;;(add-to-list 'package-archives '("melpa-stable" . "https://stable.melpa.org/packages/") t)
(package-initialize)

Note that you'll need to run M-x package-refresh-contents or M-x package-list-packages to ensure that Emacs has fetched the MELPA package list before you can install packages with M-x package-install or similar.

Installing Melpa Stable

To use the stable package repository instead of the default “bleeding-edge” repository, use this instead of "melpa":

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

Installing a package

To install a package run M-x package-install. See Package Installation for details about that and Emacs Lisp Packages for even more information about Emacs' package manager.

Customizations

What if you only want some of your packages to be installed from MELPA, and the rest from Marmalade or elsewhere?

In Emacs 24.4 and later, package-pinned-packages allows you to exclude or include versions according to their source. For users using older versions of Emacs, we provide a package-filter.el package (available in MELPA) that will allow you to enable only certain packages or exclude certain packages. You can install the package manually by pasting this into your *scratch* buffer and evaluating it.

(progn
  (switch-to-buffer
    (url-retrieve-synchronously
      "https://raw.github.com/melpa/package-filter/master/package-filter.el"))
  (package-install-from-buffer  (package-buffer-info) 'single))

You can then customize two variables:

package-archive-enable-alist

Optional Alist of enabled packages used by package-filter. The format is (ARCHIVE . PACKAGE ...), where ARCHIVE is a string matching an archive name inpackage-archives, PACKAGE is a symbol of a package in ARCHIVE to enable.

If no ARCHIVE exists in the alist, all packages are enabled.

package-archive-exclude-alist

Alist of packages excluded by package-filter. The format is (ARCHIVE . PACKAGE ...), where ARCHIVE is a string matching an archive name in package-archives, PACKAGE is a symbol of a package in that archive to exclude.

Any specified package is excluded regardless of the value of package-archive-enable-alist

Known Issues

Failed to download ‘MELPA’ archive

This occasionally happens when using Emacs <= 26.2 with Gnutls >= 3.6. The recommended fix is to update to Emacs 26.3 or greater. Alternatively you can disable TLS1.3 by adding the following setting early in your init file. For more information see Emacs bug#34341.

(setq gnutls-algorithm-priority "NORMAL:-VERS-TLS1.3")

Dependency order is reversed

There is a small bug in Emacs 24’s package.el such that the dependency order comes out backwards. The problem is patched by some advice.

(defadvice package-compute-transaction
    (around package-compute-transaction-fix activate)
  "Fix order of requirements."
  (let ((package-list (ad-get-arg 0)))
    (let (package-list)
      (ad-set-args 0 (list nil  (ad-get-arg 1)))
      ad-do-it)
    (dolist (elt (nreverse ad-return-value))
      (setq package-list (cons elt (delq elt package-list))))
    (setq ad-return-value package-list)))

Updating Packages

After running package-list-packages, type U (mark Upgradable packages) and then x (eXecute the installs and deletions). When it’s done installing all the packages it will ask if you want to delete the obsolete packages and so you can hit y (Yes).

If you run into a problem installing or upgrading, you may need to go into your ~/.emacs.d/elpa/ directory and delete packages that are installed multiple times. This can happen when the install times out.

Adding a Package

In so many words, fork the project's source tree and create a pull request with a recipe for your package. The README.md file on GitHub has more details.

Development

https://github.com/melpa/melpa

Contributions are welcome. Currently, the builder supports packages using Git, Mercurial, and EmacsWiki (deprecated due to security concerns). Support for Bazaar, CVS, Darcs, Fossil and Subversion has been removed due to very limited use.